dna-sdk 0.1.0

package/dist/adapters/filesystem/source.js

@@ -0,0 +1,357 @@
+/**
+ * FilesystemSource — SourcePort backed by local .dna/ directories.
+ *
+ * 1:1 parity with Python dna.v3.adapters.filesystem.source.
+ */
+import { access, readFile, readdir, stat } from "node:fs/promises";
+import { resolve, join } from "node:path";
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+import yaml from "js-yaml";
+import { countDocs, queryDocs } from "../../kernel/protocols.js";
+import { FilesystemBundleHandle } from "../../kernel/bundle-handle.js";
+export class FilesystemSource {
+    baseDir;
+    supportsReaders = true;
+    constructor(baseDir) {
+        this.baseDir = resolve(baseDir);
+    }
+    // v1.0 — true async via fs/promises. Concurrent reads don't block
+    // the event loop, which matters for repos with many bundles or any
+    // parallel scope-load workload.
+    async loadBootstrapDocs(scope, opts) {
+        // Phase 16 — filesystem walks ``loadAll`` and filters by Kind
+        // name. SQL adapters override with a fast WHERE filter.
+        //
+        // Tenant semantics: when ``opts.tenant`` is set, the
+        // tenant-published Genome shadows the platform Genome (Phase 9).
+        // KindDefinition + LayerPolicy are non-overlayable per Phase 16 —
+        // always read from platform.
+        //
+        // 1:1 parity with Python ``FilesystemSource.load_bootstrap_docs``.
+        const { BOOTSTRAP_KIND_NAMES } = await import("../../kernel/protocols.js");
+        const bootstrapSet = new Set(BOOTSTRAP_KIND_NAMES);
+        let allRaws;
+        try {
+            allRaws = await this.loadAll(scope);
+        }
+        catch {
+            // Platform scope dir absent — tenant-only scopes still resolve.
+            allRaws = [];
+        }
+        let out = allRaws.filter((d) => bootstrapSet.has(d.kind ?? ""));
+        const tenant = opts?.tenant;
+        if (tenant) {
+            const tenantPath = join(this.baseDir, "tenants", tenant, "scopes", scope, "Genome.yaml");
+            if (await pathExists(tenantPath)) {
+                const tenantPkg = yaml.load(await readFile(tenantPath, "utf-8"));
+                if (tenantPkg
+                    && typeof tenantPkg === "object"
+                    && tenantPkg.kind === "Genome") {
+                    out = out.filter((d) => d.kind !== "Genome");
+                    out.push(tenantPkg);
+                }
+            }
+        }
+        return out;
+    }
+    async loadAll(scope, readers) {
+        const scopeDir = join(this.baseDir, scope);
+        if (!(await pathExists(scopeDir)))
+            throw new Error(`Scope not found: ${scopeDir}`);
+        return await this._loadDir(scopeDir, readers ?? [], new Set(["layers", "tenants"]));
+    }
+    /**
+     * Two-planes F2 — record-plane query over `loadAll` + the shared pure
+     * helpers (mirror of the Py `SourcePort.query` protocol-default). FS
+     * is dev-mode with small scopes; native push-down is the purview of
+     * the SQL adapters.
+     *
+     * `opts.tenant` is a documented NO-OP here: the FS TS adapter has no
+     * tenant-aware overlay merge in `loadAll` (divergence from the Py FS
+     * source, which unions base + tenant layer with shadowing) — overlay
+     * support is an F2.5 candidate alongside the writable FS source.
+     *
+     * Bundle-format kinds are not visible to this query (no kernel reader
+     * back-ref on the TS source) — record-plane docs are plain YAML.
+     */
+    async *query(scope, kind, opts = {}) {
+        const docs = await this.loadAll(scope);
+        for (const row of queryDocs(docs, kind, opts))
+            yield row;
+    }
+    /**
+     * Two-planes F2 — record-plane count over `loadAll` + `countDocs`
+     * (mirror of the Py protocol-default). Same `opts.tenant` NO-OP
+     * caveat as `query`.
+     */
+    async count(scope, kind, opts = {}) {
+        const docs = await this.loadAll(scope);
+        return countDocs(docs, kind, opts);
+    }
+    /**
+     * Explicit contract declaration (s-sourceport-contract-cleanup) — kept
+     * honest by the adapter conformance test (declaration == structural
+     * derivation). Read-only FS source: in-memory query/count + the L1
+     * granular reads (loadOne + listDocRefs, s-dna-port-surface-parity);
+     * no bundle/write surface on the TS twin yet.
+     */
+    capabilities() {
+        return {
+            source: "filesystem",
+            drafts: false,
+            versions: false,
+            layers: true,
+            bundleRead: false,
+            bundleWrite: false,
+            kernelAttachable: false,
+            granularList: true,
+            granularOne: true,
+            queryPushdown: true,
+        };
+    }
+    /**
+     * Documented NO-OP — the FS source holds no pooled resources (each read
+     * opens/closes its own file handles via fs/promises). The member exists
+     * for SourcePort surface parity with Python, where `close` is a
+     * SOURCE_PORT_CORE_MEMBERS boot-gate entry.
+     */
+    async close() {
+        // nothing to release
+    }
+    /**
+     * L1 granular access — FS impl projects from `loadAll` (mirror of the
+     * Py `FilesystemSource.list_doc_refs`): `[kind, name]` refs only, no
+     * bundle rehydration. No perf gain over `loadAll` on FS, but keeps the
+     * SourcePort contract consistent across adapters (PG is where the gain
+     * lives). Tenant: union of base + overlay with the overlay shadowing
+     * base, same as the Py twin. Result sorted by (kind, name).
+     */
+    async listDocRefs(scope, opts) {
+        const refOf = (d) => {
+            const meta = d.metadata;
+            return [
+                typeof d.kind === "string" ? d.kind : "",
+                String(meta?.name ?? d.name ?? ""),
+            ];
+        };
+        let docs;
+        if (opts?.tenant) {
+            const overlay = await this.loadLayer(scope, "tenant", opts.tenant);
+            const overlayKeys = new Set(overlay.map((d) => refOf(d).join("\0")));
+            const base = (await this.loadAll(scope)).filter((d) => !overlayKeys.has(refOf(d).join("\0")));
+            docs = [...overlay, ...base];
+        }
+        else {
+            docs = await this.loadAll(scope);
+        }
+        const refs = [];
+        for (const d of docs) {
+            const [k, n] = refOf(d);
+            if (!k || !n)
+                continue;
+            if (opts?.kind && k !== opts.kind)
+                continue;
+            refs.push([k, n]);
+        }
+        refs.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0);
+        return refs;
+    }
+    async resolveRef(scope, ref) {
+        const path = join(this.baseDir, scope, ref);
+        if (!(await pathExists(path)))
+            return "";
+        return await readFile(path, "utf-8");
+    }
+    /**
+     * L1 granular access — FS impl projects from `loadAll` (mirror of the
+     * Py `FilesystemSource.load_one`). No perf gain over `loadAll` on FS
+     * (cheap in-process disk reads) but keeps the SourcePort contract
+     * consistent across adapters. Tenant overlay shadows base: when
+     * `opts.tenant` is set the tenant layer is consulted first and the
+     * BASE layer is the fallback (same as Python — a tenant read of a doc
+     * with no overlay still returns the base doc).
+     */
+    async loadOne(scope, kind, name, opts) {
+        const readers = opts?.readers ?? [];
+        const matches = (d) => {
+            if (d.kind !== kind)
+                return false;
+            const meta = d.metadata;
+            return meta?.name === name || d.name === name;
+        };
+        if (opts?.tenant) {
+            const overlay = await this.loadLayer(scope, "tenant", opts.tenant, readers);
+            for (const d of overlay)
+                if (matches(d))
+                    return d;
+        }
+        const base = await this.loadAll(scope, readers);
+        for (const d of base)
+            if (matches(d))
+                return d;
+        return null;
+    }
+    async loadLayer(scope, layerId, layerValue, readers) {
+        // Phase 2b (parity with the Py FS source): tenant layers live at
+        // tenants/<X>/scopes/<S>/; other layers (branch, region, user) keep
+        // the legacy <scope>/layers/ path. Tenant reads check the new path
+        // first, falling back to the legacy layers/tenant/<X>/ for
+        // pre-migration data.
+        if (layerId === "tenant") {
+            const newDir = join(this.baseDir, "tenants", layerValue, "scopes", scope);
+            if (await pathExists(newDir)) {
+                return await this._loadDir(newDir, readers ?? [], new Set());
+            }
+            const legacyDir = join(this.baseDir, scope, "layers", "tenant", layerValue);
+            if (await pathExists(legacyDir)) {
+                return await this._loadDir(legacyDir, readers ?? [], new Set());
+            }
+            return [];
+        }
+        const layerDir = join(this.baseDir, scope, "layers", layerId, layerValue);
+        if (!(await pathExists(layerDir)))
+            return [];
+        return await this._loadDir(layerDir, readers ?? [], new Set());
+    }
+    async _loadDir(directory, readers, skip) {
+        const documents = [];
+        const readerMatched = new Set();
+        // 1. Readers first (bundles take priority over YAML)
+        if (readers.length > 0) {
+            // Readers on the scope root directory itself (Python parity — a
+            // standalone marker like AGENTS.md at the scope root is a document
+            // of the scope; agents.md/v1 uses exactly that layout).
+            const rootHandle = new FilesystemBundleHandle(directory);
+            for (const reader of readers) {
+                try {
+                    if (await reader.detect(rootHandle)) {
+                        const doc = await reader.read(rootHandle);
+                        if (doc != null && typeof doc === "object" && "kind" in doc) {
+                            documents.push(doc);
+                        }
+                        readerMatched.add(directory.split("/").filter(Boolean).pop() ?? "");
+                    }
+                }
+                catch {
+                    // Skip reader errors (Python logs a warning and continues)
+                }
+            }
+            await this._readRecursive(directory, readers, documents, skip, readerMatched);
+        }
+        // 2. YAML files, skipping stems already matched by readers
+        await this._collectYaml(directory, directory, skip, documents, readerMatched);
+        // 3. Deduplicate by kind/name — readers (first) take priority over YAML (later)
+        const seen = new Set();
+        const deduped = [];
+        for (const doc of documents) {
+            const meta = doc.metadata ?? {};
+            const key = `${doc.kind}/${meta.name ?? ""}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                deduped.push(doc);
+            }
+        }
+        return deduped;
+    }
+    async _collectYaml(root, directory, skip, documents, readerMatched) {
+        const entries = (await readdir(directory)).sort();
+        for (const entry of entries) {
+            const full = join(directory, entry);
+            const relParts = full.slice(root.length + 1).split("/");
+            if (relParts.some((p) => skip.has(p)))
+                continue;
+            const st = await stat(full);
+            if (st.isDirectory()) {
+                await this._collectYaml(root, full, skip, documents, readerMatched);
+            }
+            else if (entry.endsWith(".yaml") || entry.endsWith(".yml")) {
+                // Dedup of reader-loaded bundles vs same-named YAML siblings is
+                // handled by step 3 ((kind, name) key) in _loadDir. Stem-only
+                // skip here would drop YAMLs of a DIFFERENT kind that happen to
+                // share a name with a bundle (e.g. Skill/create-initiative +
+                // UseCase/create-initiative — both valid, different kinds).
+                try {
+                    const content = yaml.load(await readFile(full, "utf-8"));
+                    if (content != null &&
+                        typeof content === "object" &&
+                        "kind" in content) {
+                        documents.push(content);
+                    }
+                }
+                catch {
+                    // Skip unparseable YAML
+                }
+            }
+        }
+    }
+    async _readRecursive(directory, readers, documents, skip, readerMatched) {
+        // H3 — container-aware reader routing.
+        //
+        // The scanner walks subdirs of `directory`. Each subdir IS a
+        // bundle (or a non-bundle subdir). The PARENT directory's name
+        // equals the bundle's *container* (e.g.
+        // `pageindex-documents/frank-hutter-cv/` → container =
+        // `pageindex-documents`).
+        //
+        // Pre-H3, we tried every registered reader in order and stopped
+        // at first match. That broke when two readers detected the same
+        // marker file (PageIndex + Graphify both used MANIFEST.md): the
+        // alphabetically-first extension's reader silently captured the
+        // other's bundles.
+        //
+        // H3 fix: prefer readers whose `_ownerContainer` member matches the
+        // parent dir name. Unscoped readers (undefined — a formal ReaderPort
+        // member since s-dna-rw-roundtrip-suite, no longer duck-typed) are
+        // tried only as fallback.
+        const containerName = directory.split("/").filter(Boolean).pop() ?? "";
+        const ownedReaders = readers.filter((r) => r._ownerContainer === containerName);
+        const globalReaders = readers.filter((r) => r._ownerContainer == null);
+        const orderedReaders = [...ownedReaders, ...globalReaders];
+        const entries = (await readdir(directory)).sort();
+        for (const entry of entries) {
+            const full = join(directory, entry);
+            if (!(await stat(full)).isDirectory() || skip.has(entry))
+                continue;
+            let matched = false;
+            const handle = new FilesystemBundleHandle(full);
+            for (const reader of orderedReaders) {
+                try {
+                    if (await reader.detect(handle)) {
+                        const doc = await reader.read(handle);
+                        if (doc != null &&
+                            typeof doc === "object" &&
+                            "kind" in doc) {
+                            documents.push(doc);
+                        }
+                        readerMatched.add(entry);
+                        matched = true;
+                        break;
+                    }
+                }
+                catch {
+                    // Skip reader errors
+                }
+            }
+            if (!matched) {
+                await this._readRecursive(full, readers, documents, skip, readerMatched);
+            }
+        }
+    }
+}
+// Two-planes F2 — RecordStorePort conformance BY COMPOSITION (compile-time;
+// lives in src because tsconfig excludes tests/ from `tsc --noEmit`). The
+// FS TS adapter provides the READ half (`query`|`count`) — it has no
+// save/delete yet; full conformance arrives with the writable FS source
+// (F2.5+). Function is never called — it exists for the typecheck.
+function _fsRecordStoreReadHalfConformance(src) {
+    return src;
+}
+void _fsRecordStoreReadHalfConformance;

package/dist/adapters/postgres/index.d.ts

@@ -0,0 +1,2 @@
+export { PostgresSource, type PostgresSourceOptions } from "./source.js";
+export { MIGRATIONS } from "./migrations.js";

package/dist/adapters/postgres/index.js

@@ -0,0 +1,2 @@
+export { PostgresSource } from "./source.js";
+export { MIGRATIONS } from "./migrations.js";

package/dist/adapters/postgres/migrations.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Postgres schema migrations for the SDK adapter.
+ *
+ * 1:1 parity (subset) with python/dna/adapters/postgres/source.py.
+ * v1.0 cut ships migrations 1-3:
+ *
+ *   v1 — initial: dna_documents, dna_bundle_entries
+ *   v2 — dna_layer_documents (layer overlays)
+ *   v3 — tenant column on documents + bundle_entries (Phase 2c)
+ *
+ * Future migrations (versions table, lockfile, eventbus) land here as
+ * the TS Postgres adapter grows toward full Python parity.
+ */
+export declare const MIGRATIONS: Record<number, string[]>;

package/dist/adapters/postgres/migrations.js

@@ -0,0 +1,88 @@
+/**
+ * Postgres schema migrations for the SDK adapter.
+ *
+ * 1:1 parity (subset) with python/dna/adapters/postgres/source.py.
+ * v1.0 cut ships migrations 1-3:
+ *
+ *   v1 — initial: dna_documents, dna_bundle_entries
+ *   v2 — dna_layer_documents (layer overlays)
+ *   v3 — tenant column on documents + bundle_entries (Phase 2c)
+ *
+ * Future migrations (versions table, lockfile, eventbus) land here as
+ * the TS Postgres adapter grows toward full Python parity.
+ */
+export const MIGRATIONS = {
+    1: [
+        `CREATE TABLE IF NOT EXISTS {schema}.dna_documents (
+       scope      TEXT NOT NULL,
+       kind       TEXT NOT NULL,
+       name       TEXT NOT NULL,
+       content    JSONB NOT NULL,
+       version    INTEGER NOT NULL DEFAULT 1,
+       updated_at TEXT NOT NULL,
+       PRIMARY KEY (scope, kind, name)
+     )`,
+        `CREATE TABLE IF NOT EXISTS {schema}.dna_bundle_entries (
+       scope      TEXT NOT NULL,
+       kind       TEXT NOT NULL,
+       name       TEXT NOT NULL,
+       entry_path TEXT NOT NULL,
+       content    TEXT NOT NULL,
+       updated_at TEXT NOT NULL,
+       PRIMARY KEY (scope, kind, name, entry_path)
+     )`,
+        `CREATE INDEX IF NOT EXISTS dna_bundle_entries_scope_kind_idx
+       ON {schema}.dna_bundle_entries (scope, kind)`,
+    ],
+    2: [
+        `CREATE TABLE IF NOT EXISTS {schema}.dna_layer_documents (
+       scope       TEXT NOT NULL,
+       layer_id    TEXT NOT NULL,
+       layer_value TEXT NOT NULL,
+       kind        TEXT NOT NULL,
+       name        TEXT NOT NULL,
+       content     JSONB NOT NULL,
+       updated_at  TEXT NOT NULL,
+       PRIMARY KEY (scope, layer_id, layer_value, kind, name)
+     )`,
+    ],
+    3: [
+        `ALTER TABLE {schema}.dna_documents ADD COLUMN IF NOT EXISTS tenant TEXT NOT NULL DEFAULT ''`,
+        `ALTER TABLE {schema}.dna_bundle_entries ADD COLUMN IF NOT EXISTS tenant TEXT NOT NULL DEFAULT ''`,
+        `ALTER TABLE {schema}.dna_documents DROP CONSTRAINT IF EXISTS dna_documents_pkey`,
+        `ALTER TABLE {schema}.dna_documents ADD PRIMARY KEY (scope, kind, name, tenant)`,
+        `ALTER TABLE {schema}.dna_bundle_entries DROP CONSTRAINT IF EXISTS dna_bundle_entries_pkey`,
+        `ALTER TABLE {schema}.dna_bundle_entries ADD PRIMARY KEY (scope, kind, name, entry_path, tenant)`,
+    ],
+    4: [
+        // v1.0 — Module catalog versioning (Phase 10 parity).
+        //
+        // `dna_versions` stores immutable per-version snapshots. Module
+        // catalog publish flow (publishModuleVersion) inserts here; list/
+        // deprecation queries read from here. Same semver pinning rules
+        // as the Python adapter — `(scope, kind, name, tenant, semver)`
+        // is unique when semver is non-NULL (immutable releases).
+        `CREATE TABLE IF NOT EXISTS {schema}.dna_versions (
+       id          BIGSERIAL PRIMARY KEY,
+       scope       TEXT NOT NULL,
+       kind        TEXT NOT NULL,
+       name        TEXT NOT NULL,
+       content     JSONB NOT NULL,
+       version     INTEGER NOT NULL,
+       semver      TEXT,
+       deprecated  BOOLEAN NOT NULL DEFAULT false,
+       deprecation_message TEXT,
+       author      TEXT,
+       created_at  TEXT NOT NULL,
+       tenant      TEXT NOT NULL DEFAULT ''
+     )`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS dna_versions_semver_unique
+       ON {schema}.dna_versions (scope, kind, name, tenant, semver)
+       WHERE semver IS NOT NULL`,
+        `CREATE INDEX IF NOT EXISTS dna_versions_module_lookup
+       ON {schema}.dna_versions (kind, scope, tenant, semver)
+       WHERE kind = 'Module' AND semver IS NOT NULL`,
+        `CREATE INDEX IF NOT EXISTS dna_versions_scope_kind_name_idx
+       ON {schema}.dna_versions (scope, kind, name, tenant)`,
+    ],
+};

package/dist/adapters/postgres/source.d.ts

@@ -0,0 +1,172 @@
+/**
+ * PostgresSource — TypeScript adapter for the SDK's WritableSourcePort.
+ *
+ * 1:1 parity (MVP) with python/dna/adapters/postgres/source.py.
+ * Implements:
+ *   - WritableSourcePort: loadBootstrapDocs, loadAll, resolveRef, loadLayer,
+ *     saveDocument, deleteDocument, publish (no-op for MVP), close
+ *   - BundleEntryReadable: fetchBundleEntry — port-aware byte fetch
+ *   - KernelAttachable: attachKernel — uniform writer/reader wiring
+ *   - Versionable: getVersion — basic single-version support
+ *
+ * Out of scope for v1.0 (lands in v1.1 follow-up):
+ *   - Module versioning catalog (Phase 10 lockfile flow)
+ *   - Tenant overlay routing (multi-tenant scopes endpoint)
+ *   - LISTEN/NOTIFY event bus (Phase 15.1)
+ *   - Draft → published two-step write flow
+ *
+ * The schema mirrors Python's `dna_documents` / `dna_bundle_entries` /
+ * `dna_layer_documents` — already-existing Python deployments are
+ * read-compatible with this adapter.
+ */
+import { Pool, type PoolConfig } from "pg";
+import type { Kernel } from "../../kernel/index.js";
+import type { ReaderPort, WritableSourcePort, WriterPort } from "../../kernel/protocols.js";
+import type { SourceCapabilities } from "../../kernel/capabilities.js";
+export interface PostgresSourceOptions {
+    /** Postgres connection string (postgresql://user:pass@host/db). */
+    connectionString?: string;
+    /** Schema to create tables in. Defaults to "public". */
+    schema?: string;
+    /**
+     * Optional pre-built Pool. When provided the adapter uses it
+     * verbatim and does NOT close it on `close()`. Useful for sharing
+     * pools across adapters or test fixtures.
+     */
+    pool?: Pool;
+    /** Initial writers (filled by attachKernel if empty). */
+    writers?: WriterPort[];
+    /** Initial readers (filled by attachKernel if empty). */
+    readers?: ReaderPort[];
+    /** Extra Pool options (max, idleTimeoutMillis, ...). */
+    poolOptions?: PoolConfig;
+}
+export declare class PostgresSource implements WritableSourcePort {
+    readonly supportsReaders = false;
+    private _pool;
+    private readonly _ownsPool;
+    private readonly _schema;
+    private _migrated;
+    _writers: WriterPort[];
+    _readers: ReaderPort[];
+    private _kernel;
+    constructor(opts: PostgresSourceOptions);
+    init(): Promise<void>;
+    /**
+     * Explicit contract declaration (s-sourceport-contract-cleanup) — kept
+     * honest by the adapter conformance test. The TS PG adapter has the
+     * write half + versions/bundle-read + the granular ref list
+     * (listDocRefs, s-dna-port-surface-parity); query/count push-down and
+     * loadOne are Py-only this phase (F2.5+ candidates).
+     */
+    capabilities(): SourceCapabilities;
+    close(): Promise<void>;
+    /**
+     * KernelAttachable interface impl. Idempotent: copies the kernel's
+     * registered writers + readers into this source so bundle writes
+     * (which depend on `_writers` producing serialised entries via
+     * `WriterPort.serialize`) work even when this source was
+     * instantiated without explicit injection.
+     */
+    attachKernel(kernel: Kernel): void;
+    private _runMigrations;
+    loadBootstrapDocs(scope: string, opts?: {
+        tenant?: string;
+    }): Promise<Record<string, unknown>[]>;
+    loadAll(scope: string, readers?: ReaderPort[]): Promise<Record<string, unknown>[]>;
+    resolveRef(_scope: string, ref: string): Promise<string>;
+    /**
+     * L1 granular access (s-dna-port-surface-parity — mirror of the Py
+     * `PostgresSource.list_doc_refs`): one indexed SELECT of `[kind, name]`
+     * refs, metadata only — no bundle entries, no reader rehydration. This
+     * is where the granular read actually pays off vs `loadAll` (which is
+     * an N+1 over bundle entries). Tenant: union of the base layer
+     * (`tenant=''`) with the overlay; refs are DISTINCT so an overlay
+     * shadow contributes a single entry.
+     */
+    listDocRefs(scope: string, opts?: {
+        kind?: string | null;
+        tenant?: string | null;
+    }): Promise<Array<[string, string]>>;
+    loadLayer(scope: string, layerId: string, layerValue: string, _readers?: ReaderPort[]): Promise<Record<string, unknown>[]>;
+    private _loadBundleEntries;
+    /**
+     * Fetch a single bundle entry by name. Mirrors Python.
+     *
+     * Disambiguation: when the kernel supplies ``kind`` (e.g.
+     * ``"GraphifyArtifact"``), the WHERE clause includes ``kind=$N``
+     * so a Skill ``foo`` and a GraphifyArtifact ``foo`` in the same
+     * scope don't collide. Without ``kind`` we fall back to
+     * ``(scope, name, entry_path)`` and accept the rare collision
+     * risk — older callers that built the kernel before the
+     * protocol gained the kwarg fall through this path.
+     */
+    fetchBundleEntry(scope: string, container: string, name: string, entry: string, options?: {
+        tenant?: string | null;
+        kind?: string | null;
+    }): Promise<Uint8Array>;
+    saveDocument(scope: string, kind: string, name: string, raw: Record<string, unknown>, options?: {
+        author?: string;
+        tenant?: string | null;
+        layer?: [string, string];
+        versionRetention?: number | null;
+    }): Promise<string>;
+    deleteDocument(scope: string, kind: string, name: string, options?: {
+        author?: string;
+        tenant?: string | null;
+        layer?: [string, string];
+    }): Promise<void>;
+    /**
+     * MVP no-op: PostgresSource saves directly to dna_documents
+     * (no draft state). Future v1.1 may introduce drafts → publish
+     * promotion; the method exists today so callers expecting it
+     * (e.g. cross-language migrations from Python) don't break.
+     */
+    publish(_scope: string, _kind: string, _name: string): Promise<string>;
+    getVersion(scope: string, kind: string, name: string, versionId: string): Promise<Record<string, unknown>>;
+    /**
+     * Publish an immutable Module version with semver. Mirrors the Python
+     * Phase 10 `publishModuleVersion` flow:
+     *
+     *   1. Reject re-publish of an existing (scope, name, semver, tenant).
+     *   2. Insert the row into dna_versions with semver set.
+     *   3. Mirror the row to dna_documents (latest-stable view) so
+     *      `loadAll` continues returning the freshest content.
+     *
+     * Throws `VersionAlreadyPublished` when the (scope, kind, name,
+     * tenant, semver) tuple already exists. This is the immutability
+     * guarantee — once published, that version is frozen.
+     */
+    publishModuleVersion(scope: string, name: string, raw: Record<string, unknown>, semver: string, options?: {
+        tenant?: string | null;
+        author?: string;
+    }): Promise<{
+        id: number;
+        semver: string;
+    }>;
+    /**
+     * List published versions of a Module. Returns newest-first by
+     * semver lexicographic order (good enough for typical X.Y.Z;
+     * v1.1 may add proper semver comparison).
+     */
+    listModuleVersions(scope: string, name: string, options?: {
+        tenant?: string | null;
+        includeDeprecated?: boolean;
+    }): Promise<Array<{
+        id: number;
+        semver: string;
+        version: number;
+        deprecated: boolean;
+        deprecationMessage: string | null;
+        author: string | null;
+        createdAt: string;
+    }>>;
+    /**
+     * Mark a published Module version as deprecated. The row stays
+     * (immutability), but listModuleVersions can filter it out via
+     * `includeDeprecated: false`.
+     */
+    deprecateModuleVersion(scope: string, name: string, semver: string, message?: string, options?: {
+        tenant?: string | null;
+    }): Promise<void>;
+}