dna-sdk 0.1.0

package/dist/kernel/lock-manager.d.ts

@@ -0,0 +1,21 @@
+/**
+ * LockManager — namespace class extracting lockfile logic
+ * from ManifestInstance.
+ *
+ * Usage: `mi.lock.generate()` — equivalent to `mi.generateLock()`.
+ *
+ * This is an extraction (Chunk 2 of the kernel simplification plan).
+ * The original methods on ManifestInstance are preserved; both APIs
+ * return identical results.
+ */
+import { type Lockfile } from "./lock.js";
+import type { ManifestInstance } from "./instance.js";
+export declare class LockManager {
+    private host;
+    constructor(host: ManifestInstance);
+    /**
+     * Generate a lockfile snapshot from the current documents.
+     * Equivalent to `mi.generateLock()`.
+     */
+    generate(): Lockfile;
+}

package/dist/kernel/lock-manager.js

@@ -0,0 +1,43 @@
+/**
+ * LockManager — namespace class extracting lockfile logic
+ * from ManifestInstance.
+ *
+ * Usage: `mi.lock.generate()` — equivalent to `mi.generateLock()`.
+ *
+ * This is an extraction (Chunk 2 of the kernel simplification plan).
+ * The original methods on ManifestInstance are preserved; both APIs
+ * return identical results.
+ */
+import { documentHash } from "./lock.js";
+// ---------------------------------------------------------------------------
+// LockManager
+// ---------------------------------------------------------------------------
+export class LockManager {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * Generate a lockfile snapshot from the current documents.
+     * Equivalent to `mi.generateLock()`.
+     */
+    generate() {
+        const entries = this.host.documents.map((d) => {
+            const sha = documentHash(d.raw);
+            return {
+                name: d.name,
+                kind: d.kind,
+                apiVersion: d.apiVersion,
+                origin: d.origin,
+                path: "",
+                sha256: sha,
+            };
+        });
+        return {
+            scope: this.host.scope,
+            documents: entries,
+            lockVersion: 3,
+            generatedAt: new Date().toISOString(),
+        };
+    }
+}

package/dist/kernel/lock.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Lockfile types and utilities — snapshot of resolved documents.
+ *
+ * 1:1 parity with Python lockfile structures.
+ */
+export interface LockEntry {
+    name: string;
+    kind: string;
+    apiVersion: string;
+    origin: string;
+    path: string;
+    sha256: string;
+}
+export interface Lockfile {
+    scope: string;
+    documents: LockEntry[];
+    lockVersion: number;
+    generatedAt: string;
+}
+export interface VerifyResult {
+    added: string[];
+    removed: string[];
+    changed: string[];
+    ok: boolean;
+}
+/**
+ * Compute SHA-256 hash of a document's raw dict.
+ *
+ * Matches Python's: hashlib.sha256(json.dumps(raw, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+ */
+export declare function documentHash(raw: Record<string, unknown>): string;
+export declare function writeLockfile(lock: Lockfile, path: string): void;
+export declare function readLockfile(path: string): Lockfile;
+export declare function verifyLock(documents: {
+    kind: string;
+    name: string;
+    raw: Record<string, unknown>;
+}[], lockPath: string): VerifyResult;

package/dist/kernel/lock.js

@@ -0,0 +1,115 @@
+/**
+ * Lockfile types and utilities — snapshot of resolved documents.
+ *
+ * 1:1 parity with Python lockfile structures.
+ */
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { sha256 } from "js-sha256";
+import yaml from "js-yaml";
+/**
+ * Serialize a value to JSON matching Python's json.dumps(sort_keys=True, ensure_ascii=False).
+ *
+ * Key differences from JSON.stringify:
+ * - Object keys are recursively sorted (not just top-level)
+ * - Separators use spaces: ", " between items and ": " between key-value pairs
+ *   (Python's default separators)
+ *
+ * IMPORTANT: We cannot use JSON.stringify + regex replace because that would
+ * corrupt colons and commas inside string values (e.g., URLs like "http://host:8080").
+ * Python's json.dumps only adds spaces around STRUCTURAL separators, never inside strings.
+ */
+function pythonJsonDumps(obj) {
+    if (obj === null)
+        return "null";
+    if (typeof obj === "boolean")
+        return obj ? "true" : "false";
+    if (typeof obj === "number")
+        return JSON.stringify(obj);
+    if (typeof obj === "string")
+        return JSON.stringify(obj);
+    if (Array.isArray(obj)) {
+        return "[" + obj.map(pythonJsonDumps).join(", ") + "]";
+    }
+    // Object with sorted keys
+    const keys = Object.keys(obj).sort();
+    const pairs = keys.map((k) => JSON.stringify(k) + ": " + pythonJsonDumps(obj[k]));
+    return "{" + pairs.join(", ") + "}";
+}
+/**
+ * Compute SHA-256 hash of a document's raw dict.
+ *
+ * Matches Python's: hashlib.sha256(json.dumps(raw, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+ */
+export function documentHash(raw) {
+    const canonical = pythonJsonDumps(raw);
+    return sha256(canonical);
+}
+export function writeLockfile(lock, path) {
+    const sorted = [...lock.documents].sort((a, b) => a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind.localeCompare(b.kind));
+    const data = {
+        lockVersion: lock.lockVersion,
+        generated_at: lock.generatedAt,
+        scope: lock.scope,
+        documents: sorted.map(d => ({
+            name: d.name,
+            kind: d.kind,
+            apiVersion: d.apiVersion,
+            origin: d.origin,
+            path: d.path,
+            sha256: d.sha256,
+        })),
+    };
+    const content = `# Generated by dna install — DO NOT EDIT\n${yaml.dump(data, { sortKeys: false })}`;
+    writeFileSync(path, content);
+}
+export function readLockfile(path) {
+    if (!existsSync(path))
+        return { scope: "", documents: [], lockVersion: 3, generatedAt: "" };
+    const raw = yaml.load(readFileSync(path, "utf-8"));
+    if (!raw || !Array.isArray(raw.documents))
+        return { scope: "", documents: [], lockVersion: 3, generatedAt: "" };
+    const documents = raw.documents.map(d => ({
+        name: String(d.name ?? ""),
+        kind: String(d.kind ?? ""),
+        apiVersion: String(d.apiVersion ?? ""),
+        origin: String(d.origin ?? "local"),
+        path: String(d.path ?? ""),
+        sha256: String(d.sha256 ?? ""),
+    }));
+    return {
+        scope: String(raw.scope ?? ""),
+        documents,
+        lockVersion: Number(raw.lockVersion ?? 3),
+        generatedAt: String(raw.generated_at ?? ""),
+    };
+}
+export function verifyLock(documents, lockPath) {
+    const lock = readLockfile(lockPath);
+    const lockMap = new Map();
+    for (const e of lock.documents)
+        lockMap.set(`${e.kind}\0${e.name}`, e.sha256);
+    const currentMap = new Map();
+    for (const d of documents) {
+        const sha = documentHash(d.raw);
+        currentMap.set(`${d.kind}\0${d.name}`, sha);
+    }
+    const added = [];
+    const removed = [];
+    const changed = [];
+    for (const [key, sha] of currentMap) {
+        const [k, n] = key.split("\0");
+        if (!lockMap.has(key)) {
+            added.push(`${k}/${n}`);
+            continue;
+        }
+        if (lockMap.get(key) !== sha)
+            changed.push(`${k}/${n}`);
+    }
+    for (const [key] of lockMap) {
+        if (!currentMap.has(key)) {
+            const [k, n] = key.split("\0");
+            removed.push(`${k}/${n}`);
+        }
+    }
+    return { added, removed, changed, ok: added.length === 0 && removed.length === 0 && changed.length === 0 };
+}

package/dist/kernel/meta.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Meta-kind machinery: DeclarativeKindPort synthesized from a
+ * TypedKindDefinition. 1:1 parity with Python dna.kernel.meta.
+ */
+import type { Document } from "./document.js";
+import { StudioUIMetadata } from "./studio_ui.js";
+import type { TypedKindDefinition } from "./models.js";
+import type { PreviewBlock } from "./preview.js";
+import { type KindPort, type LayerPolicy, type StorageDescriptor, type TenantScope } from "./protocols.js";
+/** Convert a literal YAML storage dict into a StorageDescriptor. */
+export declare function storageDictToDescriptor(storage: Record<string, unknown>): StorageDescriptor;
+/** Marker used by the 2-phase loader to distinguish synthetic ports from
+ *  extension-registered ones for conflict resolution. */
+export interface DeclarativeMarker {
+    readonly __declarative__: true;
+}
+export declare class DeclarativeKindPort implements KindPort, DeclarativeMarker {
+    readonly __declarative__: true;
+    readonly apiVersion: string;
+    readonly kind: string;
+    readonly alias: string;
+    readonly origin: string;
+    readonly docs?: string;
+    readonly isRoot: boolean;
+    readonly isPromptTarget: boolean;
+    readonly promptTargetPriority: number;
+    readonly flattenInContext: boolean;
+    readonly storage: StorageDescriptor;
+    readonly isRuntimeArtifact: boolean;
+    readonly plane: "composition" | "record";
+    readonly scope?: TenantScope;
+    readonly scopeInheritable: boolean;
+    readonly isOverlayable: boolean;
+    readonly embedFields: string[] | null;
+    private readonly _summary;
+    readonly volatileSpecFields: ReadonlySet<string>;
+    readonly graphStyle: {
+        fill: string;
+        stroke: string;
+        textColor: string;
+    };
+    readonly asciiIcon: string;
+    readonly displayLabel: string;
+    private readonly _depFilters;
+    private readonly _defaultAgent;
+    /** Public read-only view of the JSON Schema authored in the KindDefinition.
+     *  Consumers like the Studio's NewDocumentWizard use this to pre-populate
+     *  required fields with empty-but-valid stubs. */
+    readonly jsonSchema: Record<string, unknown>;
+    private readonly _validate;
+    private readonly _ajv;
+    readonly uiSchema?: Record<string, Record<string, unknown>>;
+    readonly ui?: StudioUIMetadata;
+    private readonly _describe;
+    private readonly _specDefaults;
+    private readonly _defaultAgentField;
+    readonly descriptionFallbackField?: string;
+    constructor(typedDef: TypedKindDefinition);
+    /** Load-time lint for `spec_defaults` (spec D5). Each default KEY must
+     *  exist in schema.properties and its VALUE must validate against THAT
+     *  property's subschema. `required` is intentionally IGNORED — defaults are
+     *  a *partial* spec (autolab's real _DEFAULTS doesn't satisfy required).
+     *  Twin of Python DeclarativeKindPort._lint_spec_defaults. */
+    private _lintSpecDefaults;
+    depFilters(): Record<string, string> | null;
+    getDefaultAgentName(doc: Document): string | null;
+    getLayerPolicies(_doc: Document): Record<string, LayerPolicy | string> | null;
+    parse(raw: Record<string, unknown>): unknown;
+    /** Display string for a doc (spec D3).
+     *  - Template form (string): substitute `{field}` placeholders from the
+     *    spec top level; a missing/None field renders as "".
+     *  - Projection form ({path: field}): return the spec field verbatim (or
+     *    null if absent).
+     *  - No `describe` declared → null (today's behavior).
+     *  Twin of Python DeclarativeKindPort.describe. */
+    describe(doc: Document): string | null;
+    private static readonly _PROJECTION_KEYS;
+    private static readonly _PROJECTION_MARKERS;
+    private static _isProjection;
+    /** Load-time lint for projection objects in `summary:` (spec D2). Unknown
+     *  key → throw; exactly one resolver; `format`/`paths` exclusivity. Twin of
+     *  Python `_lint_summary`. */
+    private static _lintSummary;
+    /** Dict-only walk over a dotted `a.b.c` path. Missing → null. */
+    private static _walkPath;
+    /** Decimal rounding that is byte-behavior-identical to CPython's built-in
+     *  `round(value, ndigits)` — i.e. a faithful port of CPython `double_round`.
+     *
+     *  CPython rounds the EXACT stored IEEE-754 double to `ndigits` decimal
+     *  places, ties-to-even, on the *true binary* value. A naive
+     *  `Math.round(value * 10^n) / 10^n` (round-half-away, and on the *scaled*
+     *  double) diverges on the genuine half cases — e.g. `0.125@2` is exactly
+     *  1/8 so CPython ties to even → `0.12`, whereas `Math.round` gives `0.13`;
+     *  and `2.675@2` stores as `2.67499…` so CPython → `2.67`. To match all of
+     *  these we decompose the double into its exact rational `mantissa·2^exp2`,
+     *  scale by `10^ndigits` with exact BigInt arithmetic, and round-half-to-even
+     *  on the exact remainder. Verified against CPython `round` over a 20k-case
+     *  Monte-Carlo (n∈{1,2,3,4}) plus the pinned hard cases: 0 mismatches.
+     *
+     *  Real consumers only use round:4 (avg_score/cost); this keeps the deeper
+     *  depths (round:2, the spec's #1 parity risk) identical too. */
+    private static _bankersRound;
+    private static _resolveProjection;
+    /** Declarative projection (F3 spec D2): when the KindDefinition declares
+     *  `summary: {field: <plain default | projection object>}`, project the
+     *  doc's spec. A PLAIN value keeps today's meaning (present field from
+     *  spec, else the declared default). A PROJECTION object runs the closed
+     *  vocabulary (count_of/path/paths/format + combinators). No declaration →
+     *  null (today's behavior). Twin of Python DeclarativeKindPort.summary. */
+    summary(doc: Document): Record<string, unknown> | null;
+    promptTemplate(): string | null;
+    dependencies(): Record<string, string> | null;
+    schema(): Record<string, unknown> | null;
+    /**
+     * Preview blocks derived from the kind's JSON schema. Walks the
+     * top-level `properties` of `jsonSchema` and renders each one based on
+     * its declared type:
+     *   - string with format=markdown OR maxLength>=400 → markdown block
+     *   - string                                       → fields entry
+     *   - integer / number / boolean                    → fields entry
+     *   - array of strings                              → fields entry (bullets)
+     *   - array of objects / object                     → code block (json)
+     *   - enum                                          → fields entry
+     *
+     * Required fields surface first, optional after.
+     */
+    preview(doc: Document): PreviewBlock[];
+    static fromTyped(typedDef: TypedKindDefinition): DeclarativeKindPort;
+}
+/**
+ * Walk a JSON Schema's top-level `properties` and produce a uiSchema map
+ * keyed by field name. Required fields get `required: true` so the
+ * SchemaDrivenEditor can mark them visually if it chooses to.
+ */
+export declare function deriveUiSchemaFromJsonSchema(jsonSchema: Record<string, unknown>): Record<string, Record<string, unknown>>;