dna-sdk 0.1.0

package/dist/kernel/protocols.js

@@ -0,0 +1,493 @@
+/**
+ * v3 Kernel Protocols — the 5 ports + shared types.
+ *
+ * Parity with Python dna.kernel.protocols is SURFACE-TRACKED, not
+ * assumed (s-dna-port-surface-parity): every port's member list — and every
+ * INTENTIONAL asymmetry, with its justification — lives in the shared
+ * fixture `tests/parity-fixtures/port-surface-parity.json`, enforced by
+ * `tests/port-surface-parity.test.ts` (via the keyof-bound PORT_SURFACE
+ * manifest in `./port-surface.ts`) and by the Python twin
+ * `packages/sdk-py/tests/test_port_surface_parity.py` (real Protocol
+ * introspection). Adding/removing a member on either side without updating
+ * the fixture turns the suites red.
+ */
+// ---------------------------------------------------------------------------
+// Layer policy
+// ---------------------------------------------------------------------------
+export const LayerPolicy = {
+    OPEN: "open",
+    RESTRICTED: "restricted",
+    LOCKED: "locked",
+};
+// ---------------------------------------------------------------------------
+// Tenant scope (Kubernetes-style: each KindPort declares its scope)
+// ---------------------------------------------------------------------------
+/**
+ * Whether a Kind's documents belong to a tenant or are globally shared.
+ *
+ * Mirrors the Kubernetes CRD `scope: Namespaced | Cluster` model. Each
+ * KindPort declares its scope; the kernel enforces it on every write.
+ *
+ * - `TENANTED` (default): documents belong to one tenant. Writing
+ *   requires a tenant arg; reading is filtered by tenant.
+ *   Agent, EvalCase, EvalRun, AssessmentRun, Finding, etc.
+ * - `GLOBAL`: documents are shared across all tenants. Writes must
+ *   not pass a tenant; reads ignore the bound tenant.
+ *   Doc, KindDefinition, Module-level configs, etc.
+ */
+export const TenantScope = {
+    TENANTED: "tenanted",
+    GLOBAL: "global",
+};
+/** Reserved tenant slugs — never accepted as user input. */
+export const RESERVED_TENANT_SLUGS = new Set([
+    "_global",
+    "_legacy",
+    "_system",
+    "",
+]);
+/**
+ * Raised when a TENANTED kind is written without a tenant arg.
+ *
+ * Bind a tenant on construction (`new Kernel({ tenant: X })`) or
+ * per-call (`kernel.withTenant(X).writeDocument(...)`).
+ */
+export class TenantRequired extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TenantRequired";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Raised when a GLOBAL kind is written with a tenant arg.
+ *
+ * Global kinds (Doc, KindDefinition, ...) are shared across
+ * tenants. Writes must explicitly omit `tenant`.
+ */
+export class TenantNotAllowed extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TenantNotAllowed";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Raised when `writeDocument` vetoes a doc whose `spec` violates the Kind's
+ * declared JSON Schema (`KindPort.schema()`).
+ *
+ * s-write-path-validation (i-008): the kernel used to validate schemas only
+ * at SCAN/read (the fail-soft `parse_error` channel) — a shape-broken doc
+ * would persist and explode later, far from the author. Now every
+ * `writeDocument` validates the spec at write time when the Kind declares a
+ * schema; Kinds without a schema stay permissive.
+ * Mode knob: `DNA_WRITE_VALIDATION=enforce|warn|off`.
+ */
+export class SpecValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SpecValidationError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Raised when a tenant slug is reserved or empty. */
+export class InvalidTenantSlug extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidTenantSlug";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Validate a tenant slug.
+ *
+ * Phase 1 only checks the reserved set + non-empty/length. Character
+ * rules (DNS-label, lowercase) are NOT enforced at the kernel boundary
+ * so existing tests/data using uppercase ("T1", "Acme") keep working.
+ * Path-traversal safety lives in the adapter.
+ *
+ * Phase 2 may tighten to k8s namespace rules (`[a-z0-9-]{1,63}`) once
+ * the migration is complete.
+ */
+export function validateTenantSlug(tenant) {
+    if (tenant === null || tenant === undefined)
+        return;
+    if (RESERVED_TENANT_SLUGS.has(tenant)) {
+        const reserved = Array.from(RESERVED_TENANT_SLUGS).sort();
+        throw new InvalidTenantSlug(`tenant slug ${JSON.stringify(tenant)} is reserved (one of ${JSON.stringify(reserved)})`);
+    }
+    if (tenant.length < 1 || tenant.length > 253) {
+        throw new InvalidTenantSlug(`tenant slug ${JSON.stringify(tenant)} must be 1-253 chars (got ${tenant.length})`);
+    }
+}
+/**
+ * Raised when a write to a layer violates the declared LayerPolicy in
+ * `Module.spec.layers`. Thrown by `Kernel.writeDocument` before the adapter
+ * is touched. Harness endpoints translate to HTTP 403.
+ */
+export class LayerPolicyViolationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LayerPolicyViolationError";
+        Object.setPrototypeOf(this, LayerPolicyViolationError.prototype);
+    }
+}
+export function isCompositionValid(result) {
+    return result.missing.length === 0;
+}
+/**
+ * Raised when a query filter / order_by is malformed in a way the
+ * adapter can detect statically (unknown operator, …). 1:1 with the Py
+ * `QueryError`.
+ */
+export class QueryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "QueryError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Operators recognized by `matchFilter` — the Py `_PG_OP_MAP` set + `in`. */
+export const QUERY_OPS = new Set([
+    "eq", "in", "like", "gt", "gte", "lt", "lte", "neq",
+]);
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * Deep structural equality for filter matching. Py uses `==` which
+ * deep-compares dicts/lists; mirror that. Best-effort divergence: Py
+ * `1 == 1.0 == True` numeric cross-type equality is NOT replicated for
+ * booleans (JS `1 !== true`) — filters should use the field's real type.
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const ka = Object.keys(a);
+        const kb = Object.keys(b);
+        return (ka.length === kb.length
+            && ka.every((k) => k in b && deepEqual(a[k], b[k])));
+    }
+    return false;
+}
+/**
+ * Walk a dotted `fieldPath` through `doc`. Unprefixed paths resolve under
+ * `spec.`; `name` is a reserved short for `metadata.name`. Returns `null`
+ * when any segment is missing (never `undefined` — parity with Py `None`).
+ */
+export function resolveFieldPath(doc, path) {
+    if (path === "name") {
+        const meta = doc.metadata;
+        return isPlainObject(meta) ? (meta.name ?? null) : null;
+    }
+    if (path === "kind")
+        return doc.kind ?? null;
+    if (path === "apiVersion")
+        return doc.apiVersion ?? null;
+    const segments = path.startsWith("metadata.") || path.startsWith("spec.") || path.startsWith("apiVersion.")
+        ? path.split(".")
+        : ["spec", ...path.split(".")];
+    let cur = doc;
+    for (const seg of segments) {
+        if (!isPlainObject(cur))
+            return null;
+        cur = cur[seg];
+        if (cur === null || cur === undefined)
+            return null;
+    }
+    return cur ?? null;
+}
+/**
+ * Evaluate a `QueryFilter` against a single doc. Unknown operators throw
+ * `QueryError` so callers can debug instead of silently matching. 1:1
+ * port of the Py `_match_filter` (only single-key dicts enter the
+ * operator branch; anything else is shorthand equality).
+ */
+export function matchFilter(doc, filter) {
+    for (const [path, expected] of Object.entries(filter)) {
+        const actual = resolveFieldPath(doc, path);
+        if (isPlainObject(expected) && Object.keys(expected).length === 1) {
+            const [op, val] = Object.entries(expected)[0];
+            if (!QUERY_OPS.has(op)) {
+                throw new QueryError(`unknown query operator ${JSON.stringify(op)} on field `
+                    + `${JSON.stringify(path)}; valid: ${[...QUERY_OPS].sort().join(", ")}`);
+            }
+            if (op === "eq" && !deepEqual(actual, val))
+                return false;
+            if (op === "neq" && deepEqual(actual, val))
+                return false;
+            if (op === "in") {
+                // Py: `actual not in (val or ())` — null/empty list matches nothing.
+                // DIVERGENCE vs Py: Py `actual in <str>` does substring membership on
+                // a malformed string operand; TS coerces non-array to [] (matches nothing).
+                const candidates = Array.isArray(val) ? val : [];
+                if (!candidates.some((v) => deepEqual(actual, v)))
+                    return false;
+            }
+            if (op === "like") {
+                if (actual === null || typeof val !== "string")
+                    return false;
+                // SQL LIKE: % = any, _ = single char. Tokenize so ONLY literals
+                // are regex-escaped (same approach as the Py fallback).
+                const parts = [];
+                for (const ch of val) {
+                    if (ch === "%")
+                        parts.push(".*");
+                    else if (ch === "_")
+                        parts.push(".");
+                    else
+                        parts.push(ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+                }
+                if (!new RegExp(`^${parts.join("")}$`).test(String(actual)))
+                    return false;
+            }
+            // Range ops: null never matches (Py: `actual is not None and …`).
+            // DIVERGENCE vs Py: Py raises TypeError on cross-type range compares;
+            // TS coerces (NaN) and silently excludes the row — don't rely on
+            // cross-type range filters.
+            /* eslint-disable @typescript-eslint/no-explicit-any */
+            if (op === "gt" && !(actual !== null && actual > val))
+                return false;
+            if (op === "gte" && !(actual !== null && actual >= val))
+                return false;
+            if (op === "lt" && !(actual !== null && actual < val))
+                return false;
+            if (op === "lte" && !(actual !== null && actual <= val))
+                return false;
+            /* eslint-enable @typescript-eslint/no-explicit-any */
+        }
+        else if (!deepEqual(actual, expected)) {
+            // Shorthand: {"status": "in-progress"} == {"status": {"eq": ...}}
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Stable sort `rows` by each `orderBy` field, last-first to achieve the
+ * desired primary/secondary precedence. Prefixed `-` means descending.
+ * `null` values sort LAST regardless of direction: the None-flag is
+ * `(v === null) !== descending` — immune to the reversed comparator
+ * (i-121: parity with PG `DESC NULLS LAST`; a plain `v === null` flag
+ * would flip under reversal and shove nulls to the FRONT in DESC).
+ *
+ * Mixed-type values (number + string across rows on the same field) fall
+ * back to stringified compare to mirror the Py TypeError fallback. Does
+ * not mutate the input. Best-effort like the Py protocol-default —
+ * adapters with native push-down use the backend's type semantics.
+ */
+export function applyOrderBy(rows, orderBy) {
+    let out = rows.slice();
+    for (const spec of [...orderBy].reverse()) {
+        const descending = spec.startsWith("-");
+        const path = descending ? spec.slice(1) : spec;
+        const decorated = out.map((row) => {
+            const v = resolveFieldPath(row, path);
+            return { row, v, flag: (v === null) !== descending };
+        });
+        // Py first pass keeps int/float (and bool, a Py int subtype) numeric
+        // and stringifies the rest; a mixed numeric/string field raises
+        // TypeError there → stringify-everything fallback. Detect the mix
+        // upfront instead of try/catch.
+        const isNumeric = (v) => typeof v === "number" || typeof v === "boolean";
+        const nonNull = decorated.filter((d) => d.v !== null);
+        const mixed = nonNull.some((d) => isNumeric(d.v)) && nonNull.some((d) => !isNumeric(d.v));
+        const sortable = (v) => {
+            if (v === null)
+                return "";
+            if (mixed)
+                return v ? String(v) : ""; // Py fallback: str(v or "")
+            return isNumeric(v) ? Number(v) : String(v);
+        };
+        const keyed = decorated.map((d) => ({ ...d, key: sortable(d.v) }));
+        const cmp = (a, b) => {
+            if (a.flag !== b.flag)
+                return a.flag ? 1 : -1;
+            if (typeof a.key === "number" && typeof b.key === "number") {
+                return a.key - b.key;
+            }
+            const sa = String(a.key);
+            const sb = String(b.key);
+            return sa < sb ? -1 : sa > sb ? 1 : 0;
+        };
+        // JS sort is stable; the negated comparator under `descending`
+        // preserves original order for ties — same as Py `reverse=True`.
+        keyed.sort((a, b) => (descending ? -cmp(a, b) : cmp(a, b)));
+        out = keyed.map((d) => d.row);
+    }
+    return out;
+}
+/**
+ * In-memory query core — mirror of the Py `SourcePort.query`
+ * protocol-default minus the IO: kind filter first (cheap), then
+ * `matchFilter`, then `applyOrderBy`, then limit/offset paging.
+ * `FilesystemSource.query` is `loadAll` + this; the shared parity
+ * fixture drives it directly.
+ */
+export function queryDocs(docs, kind, opts = {}) {
+    let kindDocs = docs.filter((d) => d.kind === kind);
+    if (opts.filter && Object.keys(opts.filter).length > 0) {
+        kindDocs = kindDocs.filter((d) => matchFilter(d, opts.filter));
+    }
+    if (opts.orderBy && opts.orderBy.length > 0) {
+        kindDocs = applyOrderBy(kindDocs, opts.orderBy);
+    }
+    const start = opts.offset ?? 0;
+    const end = opts.limit != null ? start + opts.limit : undefined;
+    return kindDocs.slice(start, end);
+}
+/**
+ * In-memory count core — mirror of the Py `SourcePort.count`
+ * protocol-default: total of docs matching the filter, optionally
+ * grouped by a field path. Groups ordered by count DESC, then key ASC
+ * with `null` LAST (matches PG `ORDER BY count DESC, key ASC NULLS
+ * LAST` and the spirit of i-121).
+ */
+export function countDocs(docs, kind, opts = {}) {
+    const rows = queryDocs(docs, kind, { filter: opts.filter });
+    const total = rows.length;
+    let groups = null;
+    if (opts.groupBy != null) {
+        const counter = new Map();
+        for (const row of rows) {
+            const v = resolveFieldPath(row, opts.groupBy);
+            // DIVERGENCE vs Py (unreachable with primitive keys, pinned for record):
+            // Py str(True)="True" / str(dict)="{'k': 1}"; JS String(true)="true" /
+            // String({})="[object Object]". Complex group keys should be avoided.
+            const key = v === null || ["string", "number", "boolean"].includes(typeof v)
+                ? v
+                : String(v);
+            counter.set(key, (counter.get(key) ?? 0) + 1);
+        }
+        groups = [...counter.entries()]
+            .map(([key, count]) => ({ key, count }))
+            .sort((a, b) => {
+            if (a.count !== b.count)
+                return b.count - a.count;
+            if ((a.key === null) !== (b.key === null))
+                return a.key === null ? 1 : -1;
+            const sa = String(a.key);
+            const sb = String(b.key);
+            return sa < sb ? -1 : sa > sb ? 1 : 0;
+        });
+    }
+    return { total, groups };
+}
+// ---------------------------------------------------------------------------
+// Error hierarchy
+// ---------------------------------------------------------------------------
+export class ResolveError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ResolveError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class ResolveNotFoundError extends ResolveError {
+    constructor(message) {
+        super(message);
+        this.name = "ResolveNotFoundError";
+    }
+}
+export class ResolveAuthError extends ResolveError {
+    constructor(message) {
+        super(message);
+        this.name = "ResolveAuthError";
+    }
+}
+export class ResolveNetworkError extends ResolveError {
+    constructor(message) {
+        super(message);
+        this.name = "ResolveNetworkError";
+    }
+}
+export const SD = {
+    bundle(container, marker, bodyAs = "text", bodyField = "instruction") {
+        return { container, pattern: "bundle", marker, bodyAs, bodyField };
+    },
+    yaml(container) {
+        return { container, pattern: "yaml" };
+    },
+    root(filename = "manifest.yaml") {
+        return { container: "", pattern: "root", marker: filename };
+    },
+    standalone(filename, bodyAs = "text", bodyField = "content") {
+        return { container: "", pattern: "standalone", marker: filename, bodyAs, bodyField };
+    },
+};
+export function defaultVisibleInBackend(storage) {
+    if (!storage)
+        return false;
+    if (storage.pattern === "bundle" || storage.pattern === "standalone")
+        return true;
+    return false;
+}
+export function resolveVisibleInBackend(kp) {
+    // `visibleInBackend` is a declared optional member of the
+    // KindPresentation slice (s-dna-kindport-descriptor-schema) — typed
+    // access, no `as any`. Unset/null falls back to the storage default.
+    const explicit = kp.visibleInBackend;
+    if (explicit !== undefined && explicit !== null)
+        return Boolean(explicit);
+    return defaultVisibleInBackend(kp.storage ?? null);
+}
+/**
+ * Phase 16 — Kinds the kernel needs registered/parsed BEFORE
+ * ``loadAll`` fires. Order is meaningful: KindDefinition first
+ * (custom Kinds need to be registered before parsing other docs),
+ * LayerPolicy next (kernel reads at write-time), Genome last
+ * (root identity).
+ */
+export const BOOTSTRAP_KIND_NAMES = ["KindDefinition", "LayerPolicy", "Genome"];
+/**
+ * Phase 16 helper — return the Genome doc for ``scope`` (or ``null``
+ * if missing). Pulls bootstrap docs and filters for the Genome Kind.
+ * Tenant-aware: when ``opts.tenant`` is set, the underlying adapter
+ * applies tenant-overlay routing (tenant-published Genome shadows
+ * platform).
+ *
+ * 1:1 parity with Python ``package_doc_for_scope``.
+ */
+export async function packageDocForScope(source, scope, opts) {
+    const bootstrap = await source.loadBootstrapDocs(scope, opts);
+    for (const d of bootstrap) {
+        if (d.kind === "Genome")
+            return d;
+    }
+    return null;
+}
+/**
+ * Concrete ToolPort implementation, stored in the kernel's ToolRegistry.
+ * Twin of the Py `ToolDefinition` dataclass — the `callable` init field
+ * holds the framework-native invocable; `getCallable()` is the canonical
+ * accessor (never serialize or wrap-replace it).
+ */
+export class ToolDefinition {
+    name;
+    group;
+    description;
+    summary;
+    argsSchema;
+    hitl;
+    scope;
+    source;
+    _callable;
+    constructor(init) {
+        this.name = init.name;
+        this.group = init.group ?? null;
+        this.description = init.description ?? "";
+        this.summary = init.summary ?? "";
+        this.argsSchema = init.argsSchema ?? {};
+        this.hitl = init.hitl ?? false;
+        this.scope = init.scope ?? null;
+        this.source = init.source ?? "";
+        this._callable = init.callable ?? null;
+    }
+    getCallable() {
+        return this._callable;
+    }
+}

package/dist/kernel/reports.d.ts

@@ -0,0 +1,26 @@
+/**
+ * ReportBuilder — structured markdown reports for eval, findings, evidence, compliance.
+ *
+ * Accessed via `mi.reports.evalSummary()`, `mi.reports.findingsSummary()`,
+ * `mi.reports.evidenceManifest()`, `mi.reports.complianceMatrix(framework)`.
+ *
+ * Each report returns Markdown with YAML frontmatter.
+ *
+ * 1:1 parity with Python dna.kernel.reports.
+ */
+import type { ManifestInstance } from "./instance.js";
+export declare class ReportBuilder {
+    private readonly _mi;
+    constructor(mi: ManifestInstance);
+    /** Generate an eval summary report grouped by suite.
+     *  If `suite` is given, only that suite is included. */
+    evalSummary(suite?: string): string;
+    /** Generate a findings summary grouped by severity.
+     *  Filters out findings with severity below `minSeverity`. */
+    findingsSummary(minSeverity?: string): string;
+    /** Generate a manifest of all evidence documents. */
+    evidenceManifest(): string;
+    /** Generate a compliance matrix mapping findings to regulatory articles.
+     *  Supported frameworks: lgpd, gdpr, nist_ai_rmf. */
+    complianceMatrix(framework: string): string;
+}