dna-sdk 0.1.0

package/dist/kernel/bundle-handle.js

@@ -0,0 +1,184 @@
+/**
+ * BundleHandle — source-agnostic interface for reading + writing a
+ * bundle's entries.
+ *
+ * 1:1 parity with python/dna/kernel/bundle_handle.py.
+ *
+ * Implementations:
+ *   - `FilesystemBundleHandle` — wraps a real filesystem directory.
+ *   - `DictBundleHandle` — in-memory, used by SQL/Postgres adapters
+ *     (rehydrate bundle entries from `dna_bundle_entries` rows into
+ *     a dict, hand to readers).
+ *   - `PostgresBundleHandle` (Postgres adapter) — backed by
+ *     `dna_bundle_entries` rows.
+ *
+ * Entry naming convention: a posix-style relative path inside the
+ * bundle. Top-level entries are bare names (`"SKILL.md"`,
+ * `"IDENTITY.md"`); nested entries use forward slashes
+ * (`"scripts/run.py"`, `"references/spec.md"`).
+ *
+ * v1.0 async refactor: read/write methods return `Promise<...>`.
+ * Async-everywhere is the contract — sync local-FS impls wrap their
+ * sync IO in `Promise.resolve` (true `fs/promises` migration is a
+ * v1.2 cleanup).
+ */
+import { access, readFile, readdir, stat, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname, basename, posix } from "node:path";
+/** True iff the path exists. fs/promises doesn't ship a boolean
+ *  `exists`; this is the canonical workaround. */
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Filesystem implementation
+// ---------------------------------------------------------------------------
+export class FilesystemBundleHandle {
+    _root;
+    constructor(_root) {
+        this._root = _root;
+    }
+    get name() { return basename(this._root); }
+    get path() { return this._root; }
+    async exists(entry) {
+        return pathExists(join(this._root, entry));
+    }
+    async readText(entry, encoding = "utf-8") {
+        const p = join(this._root, entry);
+        try {
+            return await readFile(p, encoding);
+        }
+        catch (e) {
+            if (e.code === "ENOENT") {
+                const err = new Error(`Bundle entry not found: ${entry}`);
+                err.code = "ENOENT";
+                throw err;
+            }
+            throw e;
+        }
+    }
+    async readBytes(entry) {
+        const p = join(this._root, entry);
+        try {
+            return new Uint8Array(await readFile(p));
+        }
+        catch (e) {
+            if (e.code === "ENOENT") {
+                const err = new Error(`Bundle entry not found: ${entry}`);
+                err.code = "ENOENT";
+                throw err;
+            }
+            throw e;
+        }
+    }
+    async iterEntries(recursive = false) {
+        if (!(await pathExists(this._root)))
+            return [];
+        const out = [];
+        if (recursive) {
+            const walk = async (dir, prefix) => {
+                const entries = (await readdir(dir)).sort();
+                for (const entry of entries) {
+                    const full = join(dir, entry);
+                    const rel = prefix ? posix.join(prefix, entry) : entry;
+                    const st = await stat(full);
+                    if (st.isDirectory())
+                        await walk(full, rel);
+                    else
+                        out.push(rel);
+                }
+            };
+            await walk(this._root, "");
+        }
+        else {
+            for (const entry of (await readdir(this._root)).sort())
+                out.push(entry);
+        }
+        return out;
+    }
+    async isFile(entry) {
+        const p = join(this._root, entry);
+        try {
+            return (await stat(p)).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    async writeText(entry, content, encoding = "utf-8") {
+        const p = join(this._root, entry);
+        await mkdir(dirname(p), { recursive: true });
+        await writeFile(p, content, encoding);
+    }
+    async writeBytes(entry, content) {
+        const p = join(this._root, entry);
+        await mkdir(dirname(p), { recursive: true });
+        await writeFile(p, Buffer.from(content));
+    }
+}
+// ---------------------------------------------------------------------------
+// In-memory implementation (used by tests + SQL adapters)
+// ---------------------------------------------------------------------------
+export class DictBundleHandle {
+    name;
+    _entries;
+    constructor(name, entries = {}) {
+        this.name = name;
+        this._entries = new Map(Object.entries(entries));
+    }
+    get path() { return null; }
+    async exists(entry) {
+        if (this._entries.has(entry))
+            return true;
+        // Treat parent paths as "directory entries" — true if any key
+        // starts with `entry/`.
+        const prefix = entry.endsWith("/") ? entry : `${entry}/`;
+        for (const k of this._entries.keys())
+            if (k.startsWith(prefix))
+                return true;
+        return false;
+    }
+    async readText(entry, _encoding = "utf-8") {
+        const v = this._entries.get(entry);
+        if (v === undefined) {
+            const err = new Error(`Bundle entry not found: ${entry}`);
+            err.code = "ENOENT";
+            throw err;
+        }
+        return typeof v === "string" ? v : new TextDecoder().decode(v);
+    }
+    async readBytes(entry) {
+        const v = this._entries.get(entry);
+        if (v === undefined) {
+            const err = new Error(`Bundle entry not found: ${entry}`);
+            err.code = "ENOENT";
+            throw err;
+        }
+        return typeof v === "string" ? new TextEncoder().encode(v) : v;
+    }
+    async iterEntries(recursive = false) {
+        if (recursive)
+            return Array.from(this._entries.keys()).sort();
+        // Direct children only — extract first segment, deduplicate
+        const directChildren = new Set();
+        for (const k of this._entries.keys()) {
+            const slash = k.indexOf("/");
+            directChildren.add(slash === -1 ? k : k.substring(0, slash));
+        }
+        return Array.from(directChildren).sort();
+    }
+    async isFile(entry) {
+        return this._entries.has(entry);
+    }
+    async writeText(entry, content, _encoding = "utf-8") {
+        this._entries.set(entry, content);
+    }
+    async writeBytes(entry, content) {
+        this._entries.set(entry, content);
+    }
+}

package/dist/kernel/capabilities.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Optional capability interfaces for source/cache/etc adapters.
+ *
+ * 1:1 parity with python/dna/kernel/capabilities.py.
+ *
+ * H2 — Replaces ad-hoc structural checks (`"fetchBundleEntry" in src`)
+ * with discoverable, type-checkable interface assertions. A developer
+ * authoring a custom adapter sees the available capabilities by
+ * importing this module, instead of grepping the kernel source.
+ *
+ * Why these are separate from the core `SourcePort` interface:
+ *
+ *   - The core interfaces (SourcePort, WritableSourcePort, CachePort,
+ *     ...) define the **mandatory** contract every adapter must
+ *     implement.
+ *   - These capability interfaces define **optional** features —
+ *     adapters can declare support by structurally matching the
+ *     signature, OR omit the methods entirely without breaking the
+ *     core contract.
+ *
+ * TypeScript's structural typing makes capability detection at runtime
+ * a method-presence check (`typeof src.fetchBundleEntry === "function"`).
+ * Use the helper guards (`isBundleEntryReadable`, etc.) for clarity.
+ *
+ * Adding a new capability:
+ *   1. Define `MyCapability` interface here.
+ *   2. Add an `isMyCapability(x): x is MyCapability` type guard.
+ *   3. Replace any `if ("method" in adapter)` checks with
+ *      `if (isMyCapability(adapter))`.
+ *   4. Document the capability in `docs/PORT-CONTRACT.md`.
+ *   5. Cover it in `tests/portContract.test.ts`.
+ */
+import type { Kernel } from "./index.js";
+/**
+ * Source adapter capability: fetch a single bundle entry by name.
+ *
+ * The kernel uses this to read large binary payloads (graph.json,
+ * tree.json, ...) without rehydrating the whole bundle through the
+ * Reader pipeline. Implementing adapters store bundle entries in
+ * their backing store (filesystem dir, `dna_bundle_entries` SQL
+ * table) and serve byte payloads directly.
+ *
+ * Tenant overlay routing: when `tenant` is provided and the adapter
+ * supports it, the tenant-scoped copy is preferred over the base
+ * layer.
+ *
+ * Throws `Error` (with code `ENOENT` or message containing "not
+ * found") when the bundle or entry is absent.
+ */
+export interface BundleEntryReadable {
+    fetchBundleEntry(scope: string, container: string, name: string, entry: string, 
+    /**
+     * Optional knobs:
+     *   - ``tenant`` — when set, prefer the tenant overlay row
+     *     (with base-layer fallback).
+     *   - ``kind`` — disambiguates SQL row collision when two
+     *     Kinds share a bundle ``name`` in the same scope (e.g.
+     *     a Skill ``foo`` and a GraphifyArtifact ``foo``).
+     *     Filesystem adapters ignore this since each container
+     *     is a directory namespace.
+     */
+    options?: {
+        tenant?: string | null;
+        kind?: string | null;
+    }): Promise<Uint8Array>;
+}
+export declare function isBundleEntryReadable(x: unknown): x is BundleEntryReadable;
+/**
+ * Source adapter capability: accept post-init kernel wiring.
+ *
+ * H2 unification: `Kernel.auto({ source })` previously had a
+ * hardcoded `source instanceof FilesystemWritableSource` check that
+ * wired `_writers` and `setKernel(k)`. SQLite/Postgres adapters
+ * required the same wiring but only got it via the harness's
+ * source factory — leaving direct
+ * `new Kernel().writableSource(new SqliteSource(...))` callers with
+ * a half-broken kernel.
+ *
+ * Adapters now declare attachability by implementing
+ * `attachKernel(kernel)`. The kernel calls this method on every
+ * source it accepts — uniformly. Implementations install the
+ * kernel's `_writers`, `_readers`, and (optionally) a back-ref to
+ * the kernel itself for the source's save path to consult
+ * `storageForKind`.
+ *
+ * Idempotent: calling twice with the same kernel produces the same
+ * wired state.
+ */
+export interface KernelAttachable {
+    attachKernel(kernel: Kernel): void;
+}
+export declare function isKernelAttachable(x: unknown): x is KernelAttachable;
+/**
+ * Source adapter capability: per-Kind semver versioning.
+ *
+ * Backs the catalog versioning flow: a Kind that's `Versionable`
+ * supports `getVersion(scope, kind, name, versionId)` and
+ * `listVersions(...)`. The harness REST surface checks for this
+ * capability via `isVersionable` to decide whether to expose the
+ * `/catalog/{owner}/{name}/versions` endpoint (501 otherwise).
+ *
+ * Custom adapters that don't track per-doc versions can omit and
+ * the harness will degrade gracefully with a 501 response.
+ */
+export interface Versionable {
+    getVersion(scope: string, kind: string, name: string, versionId: string): Promise<Record<string, unknown>>;
+}
+export declare function isVersionable(x: unknown): x is Versionable;
+/**
+ * Typed view of what a source adapter supports — TS twin of the Py
+ * `SourceCapabilities` dataclass (s-sourceport-contract-cleanup).
+ *
+ * Adapters DECLARE this explicitly (`capabilities()` returns a literal);
+ * the kernel consults {@link sourceCapabilities} instead of scattering
+ * `typeof src.query === "function"` feature-tests. {@link deriveCapabilities}
+ * (structural probing) survives as (a) the conformance-test oracle that
+ * keeps declarations honest and (b) the deprecated fallback for external
+ * adapters that don't declare yet.
+ *
+ * Py-only fields with no TS meaning are omitted on purpose:
+ * `write_kwargs`/`delete_kwargs`/`tenant_layer_writes` exist in Python
+ * because optional kwargs must be probed via `inspect.signature`; the TS
+ * write surface is an options bag, so there is nothing to probe.
+ */
+export interface SourceCapabilities {
+    /** Human-readable adapter label ("filesystem", "postgres", ...). */
+    source: string;
+    drafts: boolean;
+    versions: boolean;
+    layers: boolean;
+    bundleRead: boolean;
+    bundleWrite: boolean;
+    kernelAttachable: boolean;
+    /** Implements the L1 granular reads (independent flags on purpose —
+     *  the TS FS source ships `loadOne` but not `listDocRefs`). */
+    granularList: boolean;
+    granularOne: boolean;
+    /** Implements `query`/`count` natively (FS: native but in-memory). */
+    queryPushdown: boolean;
+}
+/**
+ * Build a {@link SourceCapabilities} for `source` by structural probing —
+ * the reflection oracle. In-repo adapters declare literals instead; the
+ * conformance test asserts declaration == derivation.
+ */
+export declare function deriveCapabilities(source: unknown, label: string): SourceCapabilities;
+/**
+ * THE kernel-side accessor for a source's capabilities (TS twin of the
+ * Py `source_capabilities`). Resolution order (memoized per instance):
+ *
+ * 1. the adapter's own `capabilities()` returning a
+ *    {@link SourceCapabilities} — the explicit declaration;
+ * 2. DEPRECATED fallback: {@link deriveCapabilities} structural probing,
+ *    with a once-per-constructor console warning pointing at the
+ *    migration (keeps external adapters working).
+ */
+export declare function sourceCapabilities(source: object): SourceCapabilities;

package/dist/kernel/capabilities.js

@@ -0,0 +1,109 @@
+/**
+ * Optional capability interfaces for source/cache/etc adapters.
+ *
+ * 1:1 parity with python/dna/kernel/capabilities.py.
+ *
+ * H2 — Replaces ad-hoc structural checks (`"fetchBundleEntry" in src`)
+ * with discoverable, type-checkable interface assertions. A developer
+ * authoring a custom adapter sees the available capabilities by
+ * importing this module, instead of grepping the kernel source.
+ *
+ * Why these are separate from the core `SourcePort` interface:
+ *
+ *   - The core interfaces (SourcePort, WritableSourcePort, CachePort,
+ *     ...) define the **mandatory** contract every adapter must
+ *     implement.
+ *   - These capability interfaces define **optional** features —
+ *     adapters can declare support by structurally matching the
+ *     signature, OR omit the methods entirely without breaking the
+ *     core contract.
+ *
+ * TypeScript's structural typing makes capability detection at runtime
+ * a method-presence check (`typeof src.fetchBundleEntry === "function"`).
+ * Use the helper guards (`isBundleEntryReadable`, etc.) for clarity.
+ *
+ * Adding a new capability:
+ *   1. Define `MyCapability` interface here.
+ *   2. Add an `isMyCapability(x): x is MyCapability` type guard.
+ *   3. Replace any `if ("method" in adapter)` checks with
+ *      `if (isMyCapability(adapter))`.
+ *   4. Document the capability in `docs/PORT-CONTRACT.md`.
+ *   5. Cover it in `tests/portContract.test.ts`.
+ */
+export function isBundleEntryReadable(x) {
+    return typeof x?.fetchBundleEntry === "function";
+}
+export function isKernelAttachable(x) {
+    return typeof x?.attachKernel === "function";
+}
+export function isVersionable(x) {
+    return typeof x?.getVersion === "function";
+}
+function _fn(x, name) {
+    return typeof x?.[name] === "function";
+}
+/**
+ * Build a {@link SourceCapabilities} for `source` by structural probing —
+ * the reflection oracle. In-repo adapters declare literals instead; the
+ * conformance test asserts declaration == derivation.
+ */
+export function deriveCapabilities(source, label) {
+    return {
+        source: label,
+        drafts: _fn(source, "loadDrafts") && _fn(source, "publish"),
+        versions: _fn(source, "getVersion"),
+        layers: _fn(source, "loadLayer"),
+        bundleRead: _fn(source, "fetchBundleEntry"),
+        bundleWrite: _fn(source, "writeBundleEntry"),
+        kernelAttachable: _fn(source, "attachKernel"),
+        granularList: _fn(source, "listDocRefs"),
+        granularOne: _fn(source, "loadOne"),
+        queryPushdown: _fn(source, "query"),
+    };
+}
+const _capsCache = new WeakMap();
+const _warnedUndeclared = new Set();
+/**
+ * THE kernel-side accessor for a source's capabilities (TS twin of the
+ * Py `source_capabilities`). Resolution order (memoized per instance):
+ *
+ * 1. the adapter's own `capabilities()` returning a
+ *    {@link SourceCapabilities} — the explicit declaration;
+ * 2. DEPRECATED fallback: {@link deriveCapabilities} structural probing,
+ *    with a once-per-constructor console warning pointing at the
+ *    migration (keeps external adapters working).
+ */
+export function sourceCapabilities(source) {
+    const cached = _capsCache.get(source);
+    if (cached)
+        return cached;
+    let caps = null;
+    const fn = source.capabilities;
+    if (typeof fn === "function") {
+        try {
+            const declared = fn.call(source);
+            if (declared !== null && typeof declared === "object"
+                && typeof declared.source === "string"
+                && typeof declared.queryPushdown === "boolean") {
+                caps = declared;
+            }
+        }
+        catch {
+            caps = null; // a broken declaration degrades to derivation
+        }
+    }
+    if (caps === null) {
+        const ctor = source.constructor;
+        if (!_warnedUndeclared.has(ctor)) {
+            _warnedUndeclared.add(ctor);
+            const name = ctor?.name ?? "source";
+            console.warn(`[dna-sdk] ${name} does not declare SourceCapabilities via `
+                + `capabilities(); deriving structurally (deprecated, `
+                + `s-sourceport-contract-cleanup). Declare an explicit `
+                + `SourceCapabilities on the adapter to silence this.`);
+        }
+        caps = deriveCapabilities(source, (source.constructor?.name ?? "source"));
+    }
+    _capsCache.set(source, caps);
+    return caps;
+}

package/dist/kernel/collaborator-ports.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Narrow role-interfaces the kernel's back-ref collaborators depend on — the TS
+ * twin of Python's `dna/kernel/collaborator_ports.py`
+ * (`s-kernel-decomp-f1`, épico `e-kernel-decomposition`).
+ *
+ * A kernel collaborator that holds `this._k = kernel` should declare the NARROW
+ * slice of the kernel it actually uses, not the whole `Kernel` — otherwise the
+ * back-ref is a god-interface pushed one layer down (any collaborator can touch
+ * anything → nothing is testable in isolation). Structural typing means the
+ * `Kernel` still satisfies each interface, so the kernel keeps passing `this`
+ * when it wires the collaborator — zero runtime change.
+ *
+ * Parity note: the TS kernel decomposition tracks Python. Extracted as back-ref
+ * classes with a narrow host today: `CompositionResolver`
+ * (`CompositionResolverHost`) and `KindRegistry` (`RegistryHost`). The remaining
+ * inline collaborators (instance_builder, query_engine, bundle_io, source_sync,
+ * layer_policy, invalidation) gain their narrow interfaces as those extractions
+ * land, keeping the contract convergent per spec §6.
+ */
+import type { HookRegistry } from "./hooks.js";
+import type { KindPort, ReaderPort, SourcePort, WritableSourcePort } from "./protocols.js";
+/**
+ * The kernel surface `CompositionResolver` consumes (twin of Py
+ * `CompositionResolverHost`, though TS is leaner: the resolution-chain walk +
+ * composition-rule read touch only these). The static `INHERIT_PARENT_SCOPE`
+ * is reached via `(k.constructor as typeof Kernel)` — an explicit cast that does
+ * not need to be part of this instance contract.
+ */
+export interface CompositionResolverHost {
+    /** The active read source (getter). */
+    readonly activeSource: SourcePort | null;
+    /** Granular per-doc cache read: `[scope, kind, name, tenantOrEmpty]`. */
+    _granularDoc(key: [string, string, string, string]): Promise<Record<string, unknown> | null>;
+    /** The ordered Catalog scope set for a tenant (cached, fail-soft). */
+    _catalogScopes(tenant: string | null, opts?: {
+        exclude?: Set<string>;
+    }): Promise<Array<[string, string | null]>>;
+    /** Persist the materialized composition back through the writable source. */
+    writeDocument(scope: string, kind: string, name: string, raw: Record<string, unknown>, options?: {
+        skipHooks?: boolean;
+        author?: string;
+        tenant?: string | null;
+        layer?: [string, string];
+    }): Promise<string>;
+}
+/**
+ * The narrow slice of the Kernel the `KindRegistry` registration funnel needs
+ * (twin of Py `RegistryHost`, `s-kernel-decomp-f3-kindregistry`). The `kinds`
+ * map itself is OWNED by the registry — NOT reached through the host; this host
+ * is only the fan-out surface registration touches on the wider kernel: the
+ * hook registry (`kinddef_conflict` / `parse_error` events), the `_readers` list
+ * (the 2-phase-load rescan return gate), the generic reader/writer wiring, and
+ * the `_genericsResolved` flag it flips on every successful register. Every
+ * member is a genuine registration dependency; widening it is a code-review
+ * event (spec §3.1 / anti-goal §5.3).
+ *
+ * `_loadingExtOwner` (the per-`load()` alias-owner context) is read via
+ * optional chaining, so a kernel outside a `load()` call (where it is null) is
+ * still a valid host.
+ */
+/**
+ * The narrow slice of the Kernel the `WritePipeline` consumes (twin of Py
+ * `WriteHost`, `s-kernel-decomp-f2-writepipeline` — the anti-cosmetic F1 rule,
+ * spec §3.1). The TS write path is thinner than Python's (no invalidate tiers /
+ * OTel / catalog / observer fan-out — those "live in Python"), so this host is
+ * smaller than the Py `WriteHost`: just tenant reconciliation, the writable-
+ * source guard, the layer-policy check, the hook registry (`pre_save` veto +
+ * `post_save`/`post_delete`), and Kind identity. Widening it is a code-review
+ * event (anti-goal §5.3).
+ */
+export interface WriteHost {
+    readonly hooks: HookRegistry;
+    readonly tenant: string | null;
+    _kindScope(kind: string): string | null;
+    kindPortFor(kind: string, apiVersion?: string): KindPort | null;
+    _requireWritableSource(): WritableSourcePort;
+    _checkLayerPolicyAsync(scope: string, kind: string, name: string, raw: unknown, layer: [string, string]): Promise<void>;
+}
+export interface RegistryHost {
+    readonly hooks: HookRegistry;
+    /** The active reader list — read for the rescan gate; mutated by
+     *  `_ensureGenericReadersWriters()`. */
+    _readers: ReaderPort[];
+    /** Flipped false on every successful register so the next
+     *  `_ensureGenericReadersWriters()` re-resolves generic BUNDLE rw. */
+    _genericsResolved: boolean;
+    /** Per-`load()` alias-owner context (null outside a load). */
+    _loadingExtOwner: string | null;
+    /** Re-resolve generic BUNDLE readers/writers for newly registered kinds. */
+    _ensureGenericReadersWriters(): void;
+}

package/dist/kernel/collaborator-ports.js

@@ -0,0 +1 @@
+export {};