dna-sdk 0.1.0

package/dist/extensions/soulspec/DOCS.md

@@ -0,0 +1,19 @@
+# Soul
+
+A Soul defines an agent's personality, voice, and guiding principles as prose
+— not code. It is stored as a bundle on disk: `SOUL.md` (the canonical body)
+plus optional `STYLE.md` and `soul.json` metadata. Canonical spec:
+https://soulspec.org.
+
+When an agent references a Soul via `dep_filters.soul`, the kernel flattens
+the Soul content directly into the agent's system prompt every turn
+(`flatten_in_context=true`). Souls are great when you want several agents to
+share a voice: the Soul is the ethos, the agents are the tools.
+
+**Key fields:** `soul_content` (the prose body), `style` overrides, optional
+labels for multi-persona sets.
+
+**Divergences from canonical soulspec.org:** the helix implementation does
+not ship `IDENTITY.md` or `HEARTBEAT.md` auxiliary files. Everything lives in
+the single bundle directory and helix treats the Soul as pure prompt content
+rather than an evolving runtime artifact.

package/dist/extensions/soulspec.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SoulSpecExtension — Soul kind + SoulReader.
+ *
+ * 1:1 parity with Python dna.v3.extensions.soulspec.
+ */
+import type { BundleHandle } from "../kernel/bundle-handle.js";
+import type { FSLike } from "../kernel/fs.js";
+import type { ExtensionHost, Extension, SerializedFile, WriterPort } from "../kernel/protocols.js";
+export declare class SoulWriter implements WriterPort {
+    private fs;
+    constructor(fs?: FSLike);
+    canWrite(raw: Record<string, unknown>): boolean;
+    write(bundle: BundleHandle, raw: Record<string, unknown>): void;
+    serialize(raw: Record<string, unknown>): SerializedFile[];
+}
+export declare class SoulSpecExtension implements Extension {
+    private fs;
+    readonly name = "soulspec";
+    readonly version = "1.0.0";
+    constructor(fs?: FSLike);
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/soulspec.js

@@ -0,0 +1,287 @@
+/**
+ * SoulSpecExtension — Soul kind + SoulReader.
+ *
+ * 1:1 parity with Python dna.v3.extensions.soulspec.
+ */
+import yaml from "js-yaml";
+import { deriveFirstLine } from "../kernel/_text.js";
+import { nodeFS } from "../kernel/fs.js";
+import { KindBase } from "../kernel/kind_base.js";
+import { SoulSchema, SoulSpecSchema, zodSpecToJsonSchema } from "../kernel/models.js";
+import { SD } from "../kernel/protocols.js";
+// ---------------------------------------------------------------------------
+// Frontmatter helpers
+// ---------------------------------------------------------------------------
+function parseSoulFrontmatter(text) {
+    const match = text.match(/^---\n([\s\S]*?)---\n?([\s\S]*)$/);
+    if (!match)
+        return { metadata: {}, body: text };
+    try {
+        const parsed = yaml.load(match[1]);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            return {
+                metadata: parsed,
+                body: match[2].replace(/^\n+/, ""),
+            };
+        }
+    }
+    catch { }
+    return { metadata: {}, body: text };
+}
+// ---------------------------------------------------------------------------
+// SoulKind
+// ---------------------------------------------------------------------------
+class SoulKind extends KindBase {
+    apiVersion = "soulspec.org/v1";
+    kind = "Soul";
+    alias = "soulspec-soul";
+    isSchemaAffecting = true;
+    origin = "soulspec.org";
+    isPromptTarget = true;
+    promptTargetPriority = 1;
+    flattenInContext = true;
+    descriptionFallbackField = "soul_content";
+    storage = SD.bundle("souls", "SOUL.md");
+    graphStyle = { fill: "#8B5CF6", stroke: "#7C3AED", textColor: "#fff" };
+    asciiIcon = "🧠";
+    displayLabel = "Souls";
+    _sourceUrl = import.meta.url;
+    docs = "A Soul defines an agent's personality, voice, and guiding principles " +
+        "as prose — not code. Stored as a bundle: SOUL.md plus optional " +
+        "STYLE.md and soul.json. When an agent references a Soul, the kernel " +
+        "flattens it directly into the system prompt (flatten_in_context=true).";
+    uiSchema = {
+        soul_content: {
+            widget: "markdown-toc",
+            label: "SOUL.md",
+            help: "Main prose describing the agent's personality, voice, and principles.",
+            height: 480,
+            order: 10,
+        },
+        style_content: {
+            widget: "markdown",
+            label: "STYLE.md",
+            help: "Communication style, formatting conventions, tone.",
+            height: 260,
+            order: 20,
+        },
+        soul_json: {
+            widget: "code",
+            language: "json",
+            label: "soul.json",
+            help: "Structured soulspec.org metadata (specVersion, tags, etc.).",
+            height: 220,
+            order: 30,
+        },
+        agents_content: {
+            widget: "markdown",
+            label: "AGENTS.md (companion)",
+            help: "Optional agents.md-style workflow description.",
+            height: 220,
+            order: 40,
+        },
+        identity_content: {
+            widget: "markdown",
+            label: "IDENTITY.md",
+            help: "Who the agent is — role, background, expertise.",
+            height: 220,
+            order: 50,
+        },
+        heartbeat_content: {
+            widget: "markdown",
+            label: "HEARTBEAT.md",
+            help: "Autonomous scheduled tasks — cron for the agent, in plain language.",
+            height: 220,
+            order: 60,
+        },
+    };
+    schema() { return zodSpecToJsonSchema(SoulSpecSchema); }
+    parse(raw) {
+        return SoulSchema.parse(raw);
+    }
+    summary() { return null; }
+    promptTemplate() {
+        return "{{{soul_content}}}";
+    }
+    preview(doc) {
+        const spec = (doc.spec ?? {});
+        const blocks = [];
+        if (typeof spec.soul_content === "string" && spec.soul_content) {
+            blocks.push({ kind: "markdown", title: "SOUL.md", body: spec.soul_content });
+        }
+        if (typeof spec.style_content === "string" && spec.style_content) {
+            blocks.push({ kind: "markdown", title: "STYLE.md", body: spec.style_content });
+        }
+        if (spec.soul_json && typeof spec.soul_json === "object") {
+            blocks.push({
+                kind: "code",
+                title: "soul.json",
+                body: JSON.stringify(spec.soul_json, null, 2),
+                language: "json",
+            });
+        }
+        if (typeof spec.agents_content === "string" && spec.agents_content) {
+            blocks.push({
+                kind: "markdown",
+                title: "AGENTS.md (companion)",
+                body: spec.agents_content,
+            });
+        }
+        if (typeof spec.identity_content === "string" && spec.identity_content) {
+            blocks.push({ kind: "markdown", title: "IDENTITY.md", body: spec.identity_content });
+        }
+        if (typeof spec.heartbeat_content === "string" && spec.heartbeat_content) {
+            blocks.push({ kind: "markdown", title: "HEARTBEAT.md", body: spec.heartbeat_content });
+        }
+        if (blocks.length === 0) {
+            return [{ kind: "empty", title: "Soul (empty)" }];
+        }
+        return blocks;
+    }
+}
+// ---------------------------------------------------------------------------
+// SoulReader
+// ---------------------------------------------------------------------------
+class SoulReader {
+    fs;
+    constructor(fs) {
+        this.fs = fs;
+    }
+    detect(bundle) {
+        const path = bundle.path ?? "";
+        return this.fs.exists(`${path}/SOUL.md`) || this.fs.exists(`${path}/soul.json`);
+    }
+    read(bundle) {
+        const path = bundle.path ?? "";
+        const name = path.split("/").pop() || "";
+        const spec = {};
+        const metadata = {};
+        // Read SOUL.md — parse frontmatter if present
+        if (this.fs.exists(`${path}/SOUL.md`)) {
+            const text = this.fs.readFile(`${path}/SOUL.md`);
+            const { metadata: fm, body } = parseSoulFrontmatter(text);
+            if (Object.keys(fm).length > 0) {
+                Object.assign(metadata, fm);
+                spec.soul_content = body;
+            }
+            else {
+                spec.soul_content = text;
+            }
+        }
+        // Read soul.json
+        if (this.fs.exists(`${path}/soul.json`)) {
+            const parsed = JSON.parse(this.fs.readFile(`${path}/soul.json`));
+            spec.soul_json = parsed;
+            if (!spec.soul_content) {
+                spec.soul_content = JSON.stringify(parsed, null, 2);
+            }
+        }
+        // Companion files — soulspec.org standard
+        const companions = [
+            ["style_content", "STYLE.md"],
+            ["agents_content", "AGENTS.md"],
+            ["identity_content", "IDENTITY.md"],
+            ["heartbeat_content", "HEARTBEAT.md"],
+        ];
+        for (const [field, fname] of companions) {
+            if (this.fs.exists(`${path}/${fname}`)) {
+                spec[field] = this.fs.readFile(`${path}/${fname}`);
+            }
+        }
+        // name fallback — always ensure metadata has a name
+        if (metadata.name == null)
+            metadata.name = name;
+        return {
+            apiVersion: "soulspec.org/v1",
+            kind: "Soul",
+            metadata,
+            spec,
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// SoulWriter
+// ---------------------------------------------------------------------------
+export class SoulWriter {
+    fs;
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    canWrite(raw) {
+        return raw.kind === "Soul";
+    }
+    write(bundle, raw) {
+        const path = bundle.path ?? "";
+        this.fs.mkdir(path);
+        for (const f of this.serialize(raw)) {
+            this.fs.writeFile(`${path}/${f.relativePath}`, f.content ?? "");
+        }
+    }
+    serialize(raw) {
+        const files = [];
+        const spec = (raw.spec ?? {});
+        const meta = (raw.metadata ?? {});
+        // Build frontmatter preserving insertion order. Skip null/undefined.
+        const fm = {};
+        for (const [k, v] of Object.entries(meta)) {
+            if (v == null)
+                continue;
+            fm[k] = v;
+        }
+        const soulBody = spec.soul_content ?? "";
+        // F3 market fidelity: metadata.description may have been ENRICHED at
+        // parse time (deriveFirstLine of the body). Persisting it would emit
+        // frontmatter the source bundle never had — elide when derivable.
+        if (typeof fm.description === "string" && fm.description === deriveFirstLine(soulBody)) {
+            delete fm.description;
+        }
+        const bodyHasFm = soulBody.trimStart().startsWith("---");
+        // Byte-compat for the simple "only name" case — previous writer emitted
+        // just the body. Keeps existing fixture SOUL.md files from diffing.
+        const fmKeys = Object.keys(fm);
+        const onlyName = fmKeys.length === 0 || (fmKeys.length === 1 && fmKeys[0] === "name");
+        const needsFm = fmKeys.length > 0 && !bodyHasFm && !onlyName;
+        if (needsFm) {
+            const fmBody = yaml.dump(fm, { flowLevel: -1, sortKeys: false, lineWidth: -1 }).replace(/\n+$/, "");
+            files.push({ relativePath: "SOUL.md", content: `---\n${fmBody}\n---\n${soulBody}` });
+        }
+        else {
+            files.push({ relativePath: "SOUL.md", content: soulBody });
+        }
+        // soul.json
+        const soulJson = spec.soul_json;
+        if (soulJson) {
+            files.push({ relativePath: "soul.json", content: JSON.stringify(soulJson, null, 2) });
+        }
+        // Companion files (soulspec.org standard)
+        const companions = [
+            ["style_content", "STYLE.md"],
+            ["agents_content", "AGENTS.md"],
+            ["identity_content", "IDENTITY.md"],
+            ["heartbeat_content", "HEARTBEAT.md"],
+        ];
+        for (const [specKey, filename] of companions) {
+            const content = spec[specKey];
+            if (content) {
+                files.push({ relativePath: filename, content });
+            }
+        }
+        return files;
+    }
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+export class SoulSpecExtension {
+    fs;
+    name = "soulspec";
+    version = "1.0.0";
+    constructor(fs = nodeFS) {
+        this.fs = fs;
+    }
+    register(kernel) {
+        kernel.kind(new SoulKind());
+        kernel.reader(new SoulReader(this.fs));
+        kernel.writer(new SoulWriter(this.fs));
+    }
+}

package/dist/extensions/tenant.d.ts

@@ -0,0 +1,6 @@
+import type { ExtensionHost, Extension } from "../kernel/protocols.js";
+export declare class TenantExtension implements Extension {
+    name: string;
+    version: string;
+    register(kernel: ExtensionHost): void;
+}

package/dist/extensions/tenant.js

@@ -0,0 +1,291 @@
+/**
+ * TenantExtension — multi-tenant identity Kinds (TS twin).
+ *
+ * 1:1 parity with python/dna/extensions/tenant/__init__.py. Two GLOBAL
+ * bundle Kinds:
+ *   - Tenant (tenant-tenant) — org/team identity (TENANT.md).
+ *   - TenantMembership (tenant-membership) — user↔tenant link (MEMBERSHIP.md).
+ * Both strict-detect on apiVersion; envelope (fm.spec) reader with flat fallback.
+ */
+import yaml from "js-yaml";
+import { KindBase } from "../kernel/kind_base.js";
+import { SD, TenantScope } from "../kernel/protocols.js";
+import { popSourceFilesAsEntries, writeEntriesToHandle } from "../kernel/writer-helpers.js";
+const API_VERSION = "github.com/ruinosus/dna/tenant/v1";
+function parseFrontmatter(text) {
+    const m = text.match(/^---\n([\s\S]*?)---\n?([\s\S]*)$/);
+    if (!m)
+        return { fm: {}, body: text };
+    try {
+        const parsed = yaml.load(m[1]);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return { fm: parsed, body: (m[2] ?? "").replace(/^\n+/, "") };
+        }
+    }
+    catch {
+        // fall through
+    }
+    return { fm: {}, body: text };
+}
+function cleanSpecMeta(raw) {
+    const spec = (raw["spec"] ?? {});
+    const meta = (raw["metadata"] ?? {});
+    const cleanSpec = {};
+    for (const [k, v] of Object.entries(spec)) {
+        if (v === null || v === undefined || v === "")
+            continue;
+        if (Array.isArray(v) && v.length === 0)
+            continue;
+        if (typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0)
+            continue;
+        cleanSpec[k] = v;
+    }
+    const cleanMeta = {};
+    for (const [k, v] of Object.entries(meta)) {
+        if (v !== null && v !== undefined)
+            cleanMeta[k] = v;
+    }
+    return { cleanSpec, cleanMeta };
+}
+// ---------------------------------------------------------------------------
+// Tenant
+// ---------------------------------------------------------------------------
+class TenantKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "Tenant";
+    alias = "tenant-tenant";
+    origin = "github.com/ruinosus/dna/tenant";
+    // GLOBAL — the Tenant kind is itself global, no tenant overlay.
+    scope = TenantScope.GLOBAL;
+    storage = SD.bundle("tenants", "TENANT.md");
+    graphStyle = { fill: "#0EA5E9", stroke: "#0369A1", textColor: "#fff" };
+    asciiIcon = "🏢";
+    displayLabel = "Tenants";
+    isPromptTarget = false;
+    flattenInContext = false;
+    docs = "A Tenant is the identity of an organization/team/individual that owns scopes " +
+        "and the documents within them. Stored as bundle (TENANT.md frontmatter = spec) " +
+        "under the special `_lib` scope. Slug rules match the runtime tenant claim " +
+        "format ([a-z0-9-]{1,253}). Created by platform admins via POST /tenants. " +
+        "Suspended via PATCH; soft-deleted via DELETE (status=deleted, 30d grace period " +
+        "before physical purge by background cron). Member management lives in Phase B " +
+        "(separate TenantMembership kind).";
+    dependencies() { return null; }
+    schema() {
+        return {
+            type: "object",
+            required: ["slug", "display_name", "owner_email", "status"],
+            additionalProperties: true,
+            properties: {
+                slug: { type: "string", pattern: "^[a-z0-9-]{1,253}$", description: "Tenant identity. Used as the value of dna_documents.tenant for every doc owned by this tenant. Must match the runtime tenant claim format." },
+                display_name: { type: "string", minLength: 1, maxLength: 200, description: "Human-readable name shown in Studio." },
+                owner_email: { type: "string", format: "email", description: "Email of the human that provisioned this tenant. First member of the tenant by default." },
+                status: { type: "string", enum: ["active", "suspended", "deleted"], default: "active", description: "Lifecycle state. `deleted` is soft — docs stay in PG until the purge cron runs (~30d later)." },
+                plan: { type: "string", enum: ["free", "pro", "enterprise"], default: "free", description: "Billing/feature tier." },
+                created_at: { type: "string", format: "date-time", description: "ISO timestamp when the Tenant was provisioned." },
+                suspended_at: { type: "string", format: "date-time" },
+                deleted_at: { type: "string", format: "date-time", description: "Set on soft-delete. Cron purges ~30d later." },
+                member_count_cached: { type: "integer", minimum: 0, default: 0, description: "Denormalized count. Refreshed by membership mutations (Phase B). Eventually-consistent." },
+                metadata: { type: "object", additionalProperties: true, description: "Free-form metadata (region, lgpd_consent, billing_account_id, etc). Forward-compatible." },
+            },
+        };
+    }
+    describe(doc) {
+        const spec = (doc.spec ?? {});
+        const name = spec.display_name || spec.slug || "?";
+        return `${name} [${spec.status ?? "?"} · ${spec.plan ?? "?"}]`;
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        return {
+            slug: spec.slug ?? "",
+            display_name: spec.display_name ?? "",
+            status: spec.status ?? "active",
+            plan: spec.plan ?? "free",
+            member_count: spec.member_count_cached ?? 0,
+        };
+    }
+}
+class TenantReader {
+    async detect(bundle) {
+        if (!(await bundle.exists("TENANT.md")))
+            return false;
+        try {
+            const { fm } = parseFrontmatter(await bundle.readText("TENANT.md"));
+            return !!fm && fm["apiVersion"] === API_VERSION;
+        }
+        catch {
+            return false;
+        }
+    }
+    async read(bundle) {
+        const { fm } = parseFrontmatter(await bundle.readText("TENANT.md"));
+        if ("spec" in fm) {
+            const metadata = fm["metadata"] ?? {};
+            if (!("name" in metadata))
+                metadata["name"] = bundle.name;
+            return {
+                apiVersion: fm["apiVersion"] ?? API_VERSION,
+                kind: fm["kind"] ?? "Tenant",
+                metadata,
+                spec: fm["spec"] ?? {},
+            };
+        }
+        const name = fm["name"] ?? bundle.name;
+        delete fm["name"];
+        return { apiVersion: API_VERSION, kind: "Tenant", metadata: { name }, spec: fm };
+    }
+}
+class TenantWriter {
+    canWrite(raw) {
+        return raw["kind"] === "Tenant";
+    }
+    serialize(raw) {
+        const spec = (raw["spec"] ?? {});
+        const extraEntries = popSourceFilesAsEntries(spec, "Tenant");
+        const { cleanSpec, cleanMeta } = cleanSpecMeta(raw);
+        const envelope = {
+            apiVersion: raw["apiVersion"] ?? API_VERSION,
+            kind: raw["kind"] ?? "Tenant",
+            metadata: cleanMeta,
+            spec: cleanSpec,
+        };
+        const fmYaml = yaml.dump(envelope, { lineWidth: 100, noRefs: true, sortKeys: false }).trimEnd();
+        const slug = cleanSpec["slug"] ?? "?";
+        const display = cleanSpec["display_name"] ?? "?";
+        const status = cleanSpec["status"] ?? "active";
+        const plan = cleanSpec["plan"] ?? "free";
+        const body = `# Tenant — ${display} (\`${slug}\`)\n\n` +
+            `**Status:** ${status} · **Plan:** ${plan}\n\n` +
+            `Owner: \`${cleanSpec["owner_email"] ?? "?"}\` · ` +
+            `Created: \`${cleanSpec["created_at"] ?? "?"}\`\n\n` +
+            `All DNA documents that carry \`dna_documents.tenant = '${slug}'\` belong to ` +
+            `this Tenant. Lifecycle managed by platform admins via \`POST /tenants\`, ` +
+            `\`PATCH /tenants/{slug}\`, \`DELETE /tenants/{slug}\`.`;
+        return [{ relativePath: "TENANT.md", content: `---\n${fmYaml}\n---\n\n${body}` }, ...extraEntries];
+    }
+    async write(bundle, raw) {
+        await writeEntriesToHandle(bundle, this.serialize(raw));
+    }
+}
+// ---------------------------------------------------------------------------
+// TenantMembership
+// ---------------------------------------------------------------------------
+class TenantMembershipKind extends KindBase {
+    apiVersion = API_VERSION;
+    kind = "TenantMembership";
+    alias = "tenant-membership";
+    origin = "github.com/ruinosus/dna/tenant";
+    scope = TenantScope.GLOBAL;
+    storage = SD.bundle("tenant-memberships", "MEMBERSHIP.md");
+    graphStyle = { fill: "#8B5CF6", stroke: "#5B21B6", textColor: "#fff" };
+    asciiIcon = "👥";
+    displayLabel = "Tenant Memberships";
+    isPromptTarget = false;
+    flattenInContext = false;
+    docs = "Links a user to a Tenant with a role. One row per (tenant, user) pair. " +
+        "Created when an admin invites a member via POST /tenants/{slug}/members. " +
+        "Deleted by DELETE on same path. Tenant.spec.member_count_cached is updated " +
+        "by the route handler on each mutation (eventually-consistent).";
+    dependencies() { return null; }
+    schema() {
+        return {
+            type: "object",
+            required: ["tenant_slug", "user_email", "role", "joined_at"],
+            additionalProperties: true,
+            properties: {
+                tenant_slug: { type: "string", pattern: "^[a-z0-9-]{1,253}$", description: "Slug of the Tenant this user belongs to." },
+                user_email: { type: "string", format: "email", description: "Email identity of the user." },
+                user_id: { type: "string", description: "Stable user identifier from the IdP (Clerk sub, OIDC sub, etc). May be absent for invites pending first login — in that case user_email is the key." },
+                role: { type: "string", enum: ["owner", "admin", "member", "viewer"], default: "member", description: "Per-tenant role. `owner` is the user who provisioned the tenant (set by POST /tenants). `admin` can manage members + tenant settings. `member` can read/write scope docs. `viewer` is read-only." },
+                joined_at: { type: "string", format: "date-time", description: "ISO timestamp when the membership was created." },
+                invited_by: { type: "string", format: "email", description: "Email of the admin who invited this member." },
+                status: { type: "string", enum: ["active", "pending", "revoked"], default: "active", description: "`pending` for invites awaiting first login; `active` after first login (route handler transitions); `revoked` after admin removes." },
+                view_preset: { type: "string", description: "Optional override of Studio's auto-detected view. When set, the UI renders the curated menu/mode-tab subset matching this preset instead of deriving from the user's roles. Lets a power-user temporarily 'see as' a consumer/educator. Auto-detect from roles is the default when this is null. Values follow the same vocabulary as Role (consumer, maker, qa, po, pm, architect, tech-lead, compliance, power-user, tenant-admin, tenant-owner, platform-admin) — pick the single most-relevant intent." },
+            },
+        };
+    }
+    describe(doc) {
+        const spec = (doc.spec ?? {});
+        return `${spec.user_email ?? "?"} @ ${spec.tenant_slug ?? "?"} [${spec.role ?? "?"}]`;
+    }
+    summary(doc) {
+        const spec = (doc.spec ?? {});
+        return {
+            tenant_slug: spec.tenant_slug ?? "",
+            user_email: spec.user_email ?? "",
+            role: spec.role ?? "member",
+            status: spec.status ?? "active",
+        };
+    }
+}
+class TenantMembershipReader {
+    async detect(bundle) {
+        if (!(await bundle.exists("MEMBERSHIP.md")))
+            return false;
+        try {
+            const { fm } = parseFrontmatter(await bundle.readText("MEMBERSHIP.md"));
+            return !!fm && fm["apiVersion"] === API_VERSION && fm["kind"] === "TenantMembership";
+        }
+        catch {
+            return false;
+        }
+    }
+    async read(bundle) {
+        const { fm } = parseFrontmatter(await bundle.readText("MEMBERSHIP.md"));
+        if ("spec" in fm) {
+            const metadata = fm["metadata"] ?? {};
+            if (!("name" in metadata))
+                metadata["name"] = bundle.name;
+            return {
+                apiVersion: fm["apiVersion"] ?? API_VERSION,
+                kind: fm["kind"] ?? "TenantMembership",
+                metadata,
+                spec: fm["spec"] ?? {},
+            };
+        }
+        const name = fm["name"] ?? bundle.name;
+        delete fm["name"];
+        return { apiVersion: API_VERSION, kind: "TenantMembership", metadata: { name }, spec: fm };
+    }
+}
+class TenantMembershipWriter {
+    canWrite(raw) {
+        return raw["kind"] === "TenantMembership";
+    }
+    serialize(raw) {
+        const spec = (raw["spec"] ?? {});
+        const extraEntries = popSourceFilesAsEntries(spec, "TenantMembership");
+        const { cleanSpec, cleanMeta } = cleanSpecMeta(raw);
+        const envelope = {
+            apiVersion: raw["apiVersion"] ?? API_VERSION,
+            kind: raw["kind"] ?? "TenantMembership",
+            metadata: cleanMeta,
+            spec: cleanSpec,
+        };
+        const fmYaml = yaml.dump(envelope, { lineWidth: 100, noRefs: true, sortKeys: false }).trimEnd();
+        const userEmail = cleanSpec["user_email"] ?? "?";
+        const tenantSlug = cleanSpec["tenant_slug"] ?? "?";
+        const role = cleanSpec["role"] ?? "member";
+        const body = `# Membership — \`${userEmail}\` @ \`${tenantSlug}\`\n\n` +
+            `**Role:** ${role} · **Status:** ${cleanSpec["status"] ?? "active"}\n\n` +
+            `Joined: \`${cleanSpec["joined_at"] ?? "?"}\` · ` +
+            `Invited by: \`${cleanSpec["invited_by"] ?? "(self-provisioned)"}\``;
+        return [{ relativePath: "MEMBERSHIP.md", content: `---\n${fmYaml}\n---\n\n${body}` }, ...extraEntries];
+    }
+    async write(bundle, raw) {
+        await writeEntriesToHandle(bundle, this.serialize(raw));
+    }
+}
+export class TenantExtension {
+    name = "tenant";
+    version = "1.0.0";
+    register(kernel) {
+        kernel.kind(new TenantKind());
+        kernel.reader(new TenantReader());
+        kernel.writer(new TenantWriter());
+        kernel.kind(new TenantMembershipKind());
+        kernel.reader(new TenantMembershipReader());
+        kernel.writer(new TenantMembershipWriter());
+    }
+}

package/dist/extensions/testkit.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TestkitExtension — first-class TEST artifacts for the SDLC (TS twin).
+ *
+ * 1:1 parity with python/dna/extensions/testkit. Registers TWO artifact
+ * KindPorts (a test script is a document, like a Spec/HtmlArtifact — produced BY
+ * a work item and verifying it, not a work-item itself):
+ *
+ *   - TestGuide (testkit-test-guide) — a declarative test SCRIPT: ordered `steps`
+ *     (action → expected) that validate work items, linked via `verifies`.
+ *   - TestRun (testkit-test-run) — an EXECUTION record: `outcome`, who ran it,
+ *     per-step results + evidence. A passing run whose `verifies` points at a
+ *     Story drives the derived journey's `verify` phase.
+ *
+ * Both GLOBAL, stored under `<scope>/.dna/<scope>/test-guides|test-runs/`.
+ * Auto-exposed in Studio via `ui` metadata (generic docs surface; schema forms).
+ */
+import type { ExtensionHost, Extension, KindPort } from "../kernel/protocols.js";
+export declare class TestkitExtension implements Extension {
+    readonly name = "testkit";
+    readonly version = "1.0.0";
+    register(kernel: ExtensionHost): void;
+    /** Parity with Python's `TestkitExtension.kinds()`. */
+    kinds(): KindPort[];
+}