@githolon/dsl 0.1.0

package/src/framework/domain_lifecycle.ts

@@ -0,0 +1,108 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * The `nomos` lifecycle/controller surface.
+ *
+ * This is the Kubernetes CRD/API-server split in Nomos terms:
+ *   * `PolicyBundle` is the content-addressed package object (`policy:{hash}.bundle`);
+ *   * `DomainInstallation` is the workspace resource with spec/status/phase;
+ *   * `installDomain` writes BOTH in one intent and declares the `installDomain`
+ *     capability. This is the richer controller API; bootstrap exposes a thinner
+ *     intent with the same name and payload shape for stage-zero install.
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { Lww, MapOf } from "../drivers.js";
+import { t } from "../fields.js";
+import { directive } from "../directive.js";
+import { set, withMarker, addToSet, type PlannedOp } from "../ops.js";
+
+export const DOMAIN_INSTALLATION_PHASES = [
+  "Pending",
+  "Active",
+  "Disabled",
+  "Superseded",
+  "Retiring",
+  "Failed",
+] as const;
+export type DomainInstallationPhase = (typeof DOMAIN_INSTALLATION_PHASES)[number];
+
+export const PolicyBundle = aggregate("PolicyBundle", {
+  bundle: t.string().merge(Lww),
+});
+
+export const DomainInstallation = aggregate("DomainInstallation", {
+  "spec.domainHash": t.string().merge(Lww),
+  "spec.packageHash": t.string().merge(Lww),
+  "spec.policyAggregate": t.string().merge(Lww),
+  "spec.authorityScope": t.string().merge(Lww),
+  "spec.installedBy": t.string().merge(Lww),
+  "spec.dependencies": t.set(t.string()),
+  "spec.supersedes": t.string().merge(Lww).optional(),
+  "spec.finalizers": t.set(t.string()),
+  "metadata.generation": t.int().merge(Lww),
+  "status.phase": t.enum(DOMAIN_INSTALLATION_PHASES).merge(Lww),
+  "status.observedGeneration": t.int().merge(Lww),
+  "status.conditions": t.map(t.json()).merge(MapOf(Lww)),
+});
+
+export function policyAggregateId(domainHash: string): string {
+  return `policy:${domainHash}`;
+}
+
+export function domainInstallationAggregateId(domainHash: string): string {
+  return `domain-installation:${domainHash}`;
+}
+
+function policyBundleInstance(domainHash: string) {
+  return instance(PolicyBundle, policyAggregateId(domainHash));
+}
+
+function domainInstallationInstance(domainHash: string) {
+  return instance(DomainInstallation, domainInstallationAggregateId(domainHash));
+}
+
+export const installDomain = directive("installDomain")
+  .ensures(DomainInstallation)
+  .payload(
+    z.object({
+      domainHash: z.string(),
+      packageUsda: z.string(),
+      installedBy: z.string(),
+      authorityScope: z.string().default("workspace/root"),
+      dependencies: z.array(z.string()).default([]),
+      supersedes: z.string().optional(),
+      finalizers: z.array(z.string()).default([]),
+    }),
+  )
+  .plan((p): PlannedOp[] => {
+    const policy = policyBundleInstance(p.domainHash);
+    const install = domainInstallationInstance(p.domainHash);
+    const ops: PlannedOp[] = [
+      withMarker(set(policy, "bundle", p.packageUsda), "ensures"),
+      set(install, "spec.domainHash", p.domainHash),
+      set(install, "spec.packageHash", p.domainHash),
+      set(install, "spec.policyAggregate", policyAggregateId(p.domainHash)),
+      set(install, "spec.authorityScope", p.authorityScope),
+      set(install, "spec.installedBy", p.installedBy),
+      set(install, "metadata.generation", 1),
+      set(install, "status.phase", "Active"),
+      set(install, "status.observedGeneration", 1),
+    ];
+    if (p.dependencies.length > 0) {
+      ops.push(addToSet(install, "spec.dependencies", p.dependencies));
+    }
+    if (p.supersedes !== undefined) {
+      ops.push(set(install, "spec.supersedes", p.supersedes));
+    }
+    if (p.finalizers.length > 0) {
+      ops.push(addToSet(install, "spec.finalizers", p.finalizers));
+    }
+    return ops;
+  })
+  .requires("installDomain");

package/src/framework/identity.ts

@@ -0,0 +1,537 @@
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded
+// QuickJS engine} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
+// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+/**
+ * The `identity` domain — actors, users, and device keys.
+ *
+ * Authored against the STABLE DSL only (no kernel changes). A domain dev writes
+ * ONLY aggregates (typed fields + a merge Driver each) and directives (payload
+ * schema + plan). They NEVER write apply/fold/merge — the kernel owns the algebra.
+ *
+ * Design source: `nomos2/identity-access.md` (the actor / device-key model) and
+ * the Dart `identity_v1` domain (UserAggregate field shapes). This file models
+ * the DATA SHAPE designed in identity-access.md; it deliberately does NOT model
+ * kernel enforcement (signature verification, point-in-time authz, the
+ * partial-replication read filter) — those are later kernel slices.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * NOTES / GAPS (surface these to the kernel + design owners):
+ *
+ *  1. DRIVER PALETTE GAPS. Today the kernel ships only Lww / AddWins / MapOf /
+ *     Conflict. Several identity fields want richer semantics and are modelled
+ *     with the nearest *safe* kernel driver, flagged here:
+ *
+ *     a. IMMUTABLE-AFTER-CREATE provenance fields (actorId, userId, deviceKeyId,
+ *        publicKey, enrolledAt, registeredAt). identity-access.md: "identity =
+ *        the public key + an actor record" and a key, once enrolled, never
+ *        changes its public key. There is no `immutableAfterCreate` driver.
+ *        Modelled as `Lww` (a second write merely converges, it does not corrupt)
+ *        but the REAL semantic is create-only; a re-write should be a *rejected*
+ *        intent (C-ref, mirrors the dup-create disease in the findings). Flag:
+ *        kernel wants an immutable/create-only driver.
+ *
+ *     b. REVOCATION is append-only and POINT-IN-TIME. identity-access.md /
+ *        AC-revoke: "revocation affects FUTURE authorship only — historical
+ *        intents signed by a since-revoked key remain valid." A revoked key must
+ *        NEVER come back to life via a concurrent merge, so the device-key
+ *        lifecycle status is modelled `RemoveWins`-in-spirit. RemoveWins is NOT
+ *        in the kernel yet, so `status` is modelled as `Lww` and the revocation
+ *        is *also* recorded as an append-only set (`revokedDeviceKeyIds` AddWins
+ *        on the Actor) — the set union is monotone and revocation-wins by
+ *        construction (you can add to it, never remove from it). The Lww `status`
+ *        is the convenience read; the AddWins set is the authoritative,
+ *        revocation-wins record. Flag: kernel wants `RemoveWins` so a single
+ *        `status` field can carry revoke-wins directly.
+ *
+ *     c. lastAuthoredAt / lastSeenAt would want `numericMax` (monotonic, most
+ *        recent wins). No such driver — modelled `Lww`. Benign (these are hints,
+ *        not provenance), flagged for completeness.
+ *
+ *  2. KERNEL-ENFORCEMENT, NOT MODELLED HERE. The signature on each intent, the
+ *     committer stamp (`nomos@vX`), point-in-time authz (C-auth / AC-authz), and
+ *     the read-access replication filter (AC-read) are intent-boundary / sync
+ *     concerns the kernel owns. This domain only stores the *data* those checks
+ *     read: which keys exist, which are revoked, and as-of when. The publicKey is
+ *     stored as an opaque string leaf (base64/PEM); the kernel verifies, the DSL
+ *     does not.
+ *
+ *  3. RBAC (role-bindings) is its OWN aggregate per identity-access.md ("a
+ *     permissions aggregate"). It is event-sourced state but lives closer to the
+ *     existing `permissions_v1` domain than to identity-as-keys; it is OUT OF
+ *     SCOPE for this file (which covers actor / user / device-key only) and is
+ *     left to a permissions domain authoring pass. Flagged so the boundary is
+ *     explicit, not forgotten.
+ *
+ *  4. Enrollment is cross-actor (an admin invites → a device enrols its key).
+ *     The kernel's authz decides whether the *enroller* may enrol; here we model
+ *     the resulting data: an enrollment directive `.creates` the DeviceKey and
+ *     `.mutates` the owning Actor's key set in ONE atomic intent (the kernel
+ *     fans this out to two events, #56). The enroller's authority is a C-auth
+ *     pre-condition, not a field.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { AddWins, Lww, MapOf } from "../drivers.js";
+import { directive } from "../directive.js";
+import { addToSet, set, setEntry } from "../ops.js";
+
+/** A user/actor's lifecycle status (mirrors Dart `UserStatus`). */
+export const USER_STATUSES = ["active", "inactive", "deactivated"] as const;
+
+/**
+ * A device key's lifecycle status. A key is `enrolled` when first provisioned and
+ * `revoked` once a rotation/revocation intent retires it. Revocation is one-way
+ * (see NOTE 1b); the authoritative revoke record is the Actor's `revokedDeviceKeyIds`
+ * AddWins set — this scalar is the convenient point-read.
+ */
+export const DEVICE_KEY_STATUSES = ["enrolled", "revoked"] as const;
+
+/**
+ * The Actor aggregate — "who you are". Per identity-access.md an actor (human,
+ * service, or the kernel itself) holds keypairs; identity = the public key + an
+ * actor record. `deviceKeyIds` is the add-wins set of keys enrolled to this actor;
+ * `revokedDeviceKeyIds` is the monotone, revocation-wins record (NOTE 1b).
+ *
+ * NOTE: actorId / kind / createdAt are immutable-after-create provenance modelled
+ * as Lww (NOTE 1a). `kind` distinguishes human / service / kernel actors
+ * (identity-access.md "open: service (non-human) identities" — modelled, not
+ * enforced).
+ */
+export const ACTOR_KINDS = ["human", "service", "kernel"] as const;
+
+export const Actor = aggregate("Actor", {
+  actorId: t.string().merge(Lww), // immutable-after-create (NOTE 1a)
+  kind: t.enum(ACTOR_KINDS).merge(Lww), // immutable-after-create (NOTE 1a)
+  displayName: t.string().merge(Lww),
+  // The keys enrolled to this actor. Add-wins: a new device enrolling concurrently
+  // with another must not lose its key.
+  deviceKeyIds: t.set(t.string()).merge(AddWins),
+  // Monotone revocation record — the authoritative "revoke-wins" set (NOTE 1b).
+  // You only ever ADD to it; a revoked id can never be merged away.
+  revokedDeviceKeyIds: t.set(t.string()).merge(AddWins),
+  createdAt: t.string().merge(Lww), // ISO-8601; immutable-after-create (NOTE 1a)
+  updatedAt: t.string().merge(Lww),
+});
+
+/**
+ * The User aggregate — an actor's human-facing profile. Field shapes mirror the
+ * Dart `UserAggregate` (userId/email/status/registeredAt/updatedAt + profile).
+ * Profile is a map-of-Lww so concurrent edits to *different* profile keys (first
+ * name vs picture) both survive; same key → Lww.
+ *
+ * `actorId` links a user to its Actor (the keypair holder). A user MAY have an
+ * actor; service actors have no user. Stored as a plain id string (same-workspace
+ * link); cross-workspace edges are the kernel's routing job (not used here).
+ */
+export const User = aggregate("User", {
+  userId: t.string().merge(Lww), // immutable-after-create (NOTE 1a)
+  actorId: t.string().merge(Lww), // link to the owning Actor
+  email: t.string().merge(Lww),
+  status: t.enum(USER_STATUSES).merge(Lww),
+  // first/last name, picture url, etc. — each key merges independently by Lww.
+  profile: t.map(t.string()).merge(MapOf(Lww)),
+  registeredAt: t.string().merge(Lww), // immutable-after-create (NOTE 1a)
+  updatedAt: t.string().merge(Lww),
+});
+
+/**
+ * The DeviceKey aggregate — a device-scoped key bound to an actor. "Each device
+ * enrols its own key bound to an actor. This is what makes offline real ... and
+ * revocation fine-grained" (identity-access.md).
+ *
+ * publicKey is an opaque string leaf (base64/PEM) the KERNEL verifies; the DSL
+ * never parses it (NOTE 2). status is Lww as a convenience point-read; the
+ * authoritative revoke record is Actor.revokedDeviceKeyIds (NOTE 1b). revokedAt /
+ * revocationReason are append-only fields written once at revocation.
+ */
+export const DeviceKey = aggregate("DeviceKey", {
+  deviceKeyId: t.string().merge(Lww), // immutable-after-create (NOTE 1a)
+  actorId: t.string().merge(Lww), // immutable-after-create (NOTE 1a) — binds key to actor
+  deviceLabel: t.string().merge(Lww), // human label ("Jack's MacBook")
+  publicKey: t.string().merge(Lww), // immutable-after-create opaque leaf (NOTE 1a/2)
+  status: t.enum(DEVICE_KEY_STATUSES).merge(Lww), // convenience read (NOTE 1b)
+  enrolledAt: t.string().merge(Lww), // immutable-after-create (NOTE 1a)
+  // Set once at revocation; absent while enrolled. Neither create (enroll/rotate)
+  // folds these, so a freshly-enrolled key lacks them — OPTIONAL on the read type.
+  revokedAt: t.string().merge(Lww).optional(),
+  revocationReason: t.string().merge(Lww).optional(),
+  // Optional hint of last authorship by this key; NOT provenance (NOTE 1c). Not
+  // folded at create — OPTIONAL.
+  lastAuthoredAt: t.string().merge(Lww).optional(),
+});
+
+/**
+ * The Organization aggregate — mirrors the Dart `CreateOrganization` shape. Org
+ * metadata is a map-of-Lww; the structured PostalAddress is a JSON leaf.
+ */
+export const ORGANIZATION_TYPES = [
+  "owner",
+  "supplier",
+  "contractor",
+  "partner",
+  "other",
+] as const;
+
+export const Organization = aggregate("Organization", {
+  organizationId: t.string().merge(Lww), // immutable-after-create (NOTE 1a)
+  name: t.string().merge(Lww),
+  orgType: t.enum(ORGANIZATION_TYPES).merge(Lww),
+  // `createOrganization` folds these contact/registration scalars only when
+  // supplied — a freshly-created org may lack them — OPTIONAL on the read type.
+  description: t.string().merge(Lww).optional(),
+  website: t.string().merge(Lww).optional(),
+  primaryContactEmail: t.string().merge(Lww).optional(),
+  primaryContactPhone: t.string().merge(Lww).optional(),
+  registrationNumber: t.string().merge(Lww).optional(),
+  taxId: t.string().merge(Lww).optional(),
+  address: t.jsonObject().merge(Lww).optional(), // whole PostalAddress value object
+  organizationData: t.map(t.string()).merge(MapOf(Lww)),
+  createdBy: t.string().merge(Lww),
+  createdAt: t.string().merge(Lww),
+  updatedAt: t.string().merge(Lww),
+});
+
+/**
+ * The PublicUser aggregate — the lightweight public-facing profile index (display
+ * name, email, photo) that the old `public_user_directives` maintains, distinct
+ * from the full `User`. `email` doubles as the public index key.
+ */
+export const PublicUser = aggregate("PublicUser", {
+  userId: t.string().merge(Lww), // immutable-after-create
+  email: t.string().merge(Lww),
+  displayName: t.string().merge(Lww),
+  // `createPublicUser` folds photoUrl only when supplied — OPTIONAL (read-decode gap).
+  photoUrl: t.string().merge(Lww).optional(),
+  updatedAt: t.string().merge(Lww),
+});
+
+// ───────────────────────────── Directives ──────────────────────────────────
+
+/** registerUser — .creates the User; seeds identity + status (mirrors Dart RegisterUser). */
+export const registerUser = directive("registerUser")
+  .creates(User)
+  .payload(
+    z.object({
+      userId: z.string(),
+      actorId: z.string(),
+      email: z.string().email(),
+      firstName: z.string(),
+      lastName: z.string(),
+      registeredAt: z.string(),
+    }),
+  )
+  .plan((p) => {
+    // #105: address THIS user's concrete id (multi-instance, keyed by userId).
+    const usr = instance(User, p.userId);
+    return [
+      set(usr, "userId", p.userId),
+      set(usr, "actorId", p.actorId),
+      set(usr, "email", p.email),
+      set(usr, "status", "active"),
+      setEntry(usr, "profile", "firstName", p.firstName),
+      setEntry(usr, "profile", "lastName", p.lastName),
+      set(usr, "registeredAt", p.registeredAt),
+      set(usr, "updatedAt", p.registeredAt),
+    ];
+  });
+
+/** createActor — .creates the Actor (the keypair holder); seeds id/kind/displayName. */
+export const createActor = directive("createActor")
+  .creates(Actor)
+  .payload(
+    z.object({
+      actorId: z.string(),
+      kind: z.enum(ACTOR_KINDS),
+      displayName: z.string(),
+      createdAt: z.string(),
+    }),
+  )
+  .plan((p) => {
+    // #105: address THIS actor's concrete id (multi-instance, keyed by actorId).
+    const act = instance(Actor, p.actorId);
+    return [
+      set(act, "actorId", p.actorId),
+      set(act, "kind", p.kind),
+      set(act, "displayName", p.displayName),
+      set(act, "createdAt", p.createdAt),
+      set(act, "updatedAt", p.createdAt),
+    ];
+  });
+
+/**
+ * A profile value mirrors the v1 `UserProfile.toJson()` value space: a plain
+ * string (firstName/jobTitle/…), a bool (onboardingComplete), a NESTED MAP
+ * (notifications → 7 bools; preloadedThingIds → thingId→bool), or a list. The
+ * profile map stores Str leaves, so a NON-string value is JSON-encoded into one
+ * leaf (deterministic `JSON.stringify`); strings pass through verbatim so the
+ * existing flat-string patches lower identically. The Dart side already models a
+ * `z.record(...)` payload as `Map<String, Object?>` (codegen_dart), so this widening
+ * needs no generated-type change — only the runtime value space + lowering.
+ */
+const profileValue = z.union([
+  z.string(),
+  z.boolean(),
+  z.record(z.string(), z.unknown()), // nested map (notifications / preloadedThingIds)
+  z.array(z.unknown()), // list-valued profile entry
+]);
+
+/** Encode one profile value to the Str leaf its map key stores. Strings pass
+ *  through unchanged (flat-patch fidelity); everything else is canonical JSON. */
+function encodeProfileValue(v: z.infer<typeof profileValue>): string {
+  return typeof v === "string" ? v : JSON.stringify(v);
+}
+
+/** updateUserProfile — .mutates the User's profile map (per-key Lww). */
+export const updateUserProfile = directive("updateUserProfile")
+  .mutates(User)
+  .payload(
+    z.object({
+      userId: z.string(), // #105: target the concrete user instance.
+      updatedAt: z.string(),
+      // Partial profile patch carrying the FULL v1 UserProfile value space
+      // (string / bool / nested map / list — match `UserProfile.toJson()`); each
+      // key set independently into the Lww map (non-string values JSON-encoded).
+      profile: z.record(z.string(), profileValue),
+    }),
+  )
+  .plan((p) => {
+    const usr = instance(User, p.userId);
+    return [
+      ...Object.entries(p.profile).map(([k, v]) =>
+        setEntry(usr, "profile", k, encodeProfileValue(v)),
+      ),
+      set(usr, "updatedAt", p.updatedAt),
+    ];
+  });
+
+/** deactivateUser — .mutates the User's status (mirrors Dart DeactivateUser). */
+export const deactivateUser = directive("deactivateUser")
+  .mutates(User)
+  .payload(z.object({ userId: z.string(), updatedAt: z.string() }))
+  .plan((p) => {
+    const usr = instance(User, p.userId);
+    return [set(usr, "status", "deactivated"), set(usr, "updatedAt", p.updatedAt)];
+  });
+
+/**
+ * enrollDeviceKey — the enrollment intent (identity-access.md: "a device key is
+ * created by an enrollment intent"). It is a multi-aggregate, atomic write
+ * (#56):
+ *   - .creates the DeviceKey (status=enrolled, the opaque publicKey),
+ *   - .mutates the owning Actor's `deviceKeyIds` add-wins set.
+ * Marker is `.creates(DeviceKey)` — the new key is the lifecycle subject. The
+ * kernel lowers this to two events sharing the intent's HLC. The enroller's
+ * authority is a C-auth pre-condition, not modelled here (NOTE 4).
+ */
+export const enrollDeviceKey = directive("enrollDeviceKey")
+  .creates(DeviceKey)
+  .payload(
+    z.object({
+      deviceKeyId: z.string(),
+      actorId: z.string(),
+      deviceLabel: z.string(),
+      publicKey: z.string(),
+      enrolledAt: z.string(),
+    }),
+  )
+  .plan((p) => {
+    // #105: bind BOTH the new key instance (deviceKeyId) and the actor update onto the
+    // owning actor instance (actorId).
+    const key = instance(DeviceKey, p.deviceKeyId);
+    const act = instance(Actor, p.actorId);
+    return [
+      // The new key.
+      set(key, "deviceKeyId", p.deviceKeyId),
+      set(key, "actorId", p.actorId),
+      set(key, "deviceLabel", p.deviceLabel),
+      set(key, "publicKey", p.publicKey),
+      set(key, "status", "enrolled"),
+      set(key, "enrolledAt", p.enrolledAt),
+      // Add the key to its actor's add-wins set (a second event in the same intent).
+      addToSet(act, "deviceKeyIds", [p.deviceKeyId]),
+    ];
+  });
+
+/**
+ * revokeDeviceKey — append-only revocation. identity-access.md / AC-revoke:
+ * "revoking a key blocks FUTURE authorship by it; historical intents it signed
+ * remain valid." We model only the data shape (kernel enforces point-in-time):
+ *   - .mutates the DeviceKey: status→revoked + revokedAt/revocationReason (the
+ *     convenience point-read),
+ *   - .mutates the owning Actor's `revokedDeviceKeyIds` AddWins set — the
+ *     AUTHORITATIVE, revocation-wins record (monotone; can never be un-revoked
+ *     by a concurrent merge) (NOTE 1b).
+ * Marker is `.mutates(DeviceKey)` — revocation is a lifecycle change, not a
+ * tombstone (the key record stays, historically valid).
+ */
+export const revokeDeviceKey = directive("revokeDeviceKey")
+  .mutates(DeviceKey)
+  .payload(
+    z.object({
+      deviceKeyId: z.string(),
+      actorId: z.string(),
+      revokedAt: z.string(),
+      reason: z.string(),
+    }),
+  )
+  .plan((p) => {
+    const key = instance(DeviceKey, p.deviceKeyId);
+    const act = instance(Actor, p.actorId);
+    return [
+      set(key, "status", "revoked"),
+      set(key, "revokedAt", p.revokedAt),
+      set(key, "revocationReason", p.reason),
+      // Authoritative revoke-wins record on the Actor (a second event in the same intent).
+      addToSet(act, "revokedDeviceKeyIds", [p.deviceKeyId]),
+    ];
+  });
+
+/**
+ * rotateDeviceKey — rotation = enrol a NEW key + revoke the OLD one, atomically.
+ * identity-access.md groups "rotation / revocation" as the one append-only
+ * lifecycle intent. This is the widest multi-aggregate identity write: it touches the new DeviceKey, the
+ * old DeviceKey, and the Actor (both its add-wins enrolled set and its monotone
+ * revoked set) in ONE intent (#56). Marker `.creates(DeviceKey)` — the new key is
+ * the subject.
+ */
+export const rotateDeviceKey = directive("rotateDeviceKey")
+  .creates(DeviceKey)
+  .payload(
+    z.object({
+      actorId: z.string(),
+      oldDeviceKeyId: z.string(),
+      newDeviceKeyId: z.string(),
+      deviceLabel: z.string(),
+      newPublicKey: z.string(),
+      rotatedAt: z.string(),
+      reason: z.string(),
+    }),
+  )
+  .plan((p) => {
+    // #105: the NEW key is the subject (bound to newDeviceKeyId); the companion write
+    // targets the owning actor instance (actorId).
+    const key = instance(DeviceKey, p.newDeviceKeyId);
+    const act = instance(Actor, p.actorId);
+    return [
+      // Enrol the replacement key.
+      set(key, "deviceKeyId", p.newDeviceKeyId),
+      set(key, "actorId", p.actorId),
+      set(key, "deviceLabel", p.deviceLabel),
+      set(key, "publicKey", p.newPublicKey),
+      set(key, "status", "enrolled"),
+      set(key, "enrolledAt", p.rotatedAt),
+      // Actor: add the new key, record the old key as revoked (both add-wins/monotone).
+      addToSet(act, "deviceKeyIds", [p.newDeviceKeyId]),
+      addToSet(act, "revokedDeviceKeyIds", [p.oldDeviceKeyId]),
+    ];
+  });
+
+// ── organization ─────────────────────────────────────────────────────────────
+
+/** createOrganization — .creates the Organization (mirrors Dart CreateOrganization). */
+export const createOrganization = directive("createOrganization")
+  .creates(Organization)
+  .payload(
+    z.object({
+      organizationId: z.string(),
+      name: z.string(),
+      orgType: z.enum(ORGANIZATION_TYPES),
+      description: z.string().optional(),
+      website: z.string().optional(),
+      primaryContactEmail: z.string().optional(),
+      primaryContactPhone: z.string().optional(),
+      registrationNumber: z.string().optional(),
+      taxId: z.string().optional(),
+      address: z.string().optional(), // JSON-encoded PostalAddress
+      createdBy: z.string(),
+      createdAt: z.string(),
+    }),
+  )
+  .plan((p) => {
+    // #105: address THIS organization's concrete id (multi-instance).
+    const org = instance(Organization, p.organizationId);
+    const ops = [
+      set(org, "organizationId", p.organizationId),
+      set(org, "name", p.name),
+      set(org, "orgType", p.orgType),
+      set(org, "createdBy", p.createdBy),
+      set(org, "createdAt", p.createdAt),
+      set(org, "updatedAt", p.createdAt),
+    ];
+    if (p.description !== undefined) ops.push(set(org, "description", p.description));
+    if (p.website !== undefined) ops.push(set(org, "website", p.website));
+    if (p.primaryContactEmail !== undefined)
+      ops.push(set(org, "primaryContactEmail", p.primaryContactEmail));
+    if (p.primaryContactPhone !== undefined)
+      ops.push(set(org, "primaryContactPhone", p.primaryContactPhone));
+    if (p.registrationNumber !== undefined)
+      ops.push(set(org, "registrationNumber", p.registrationNumber));
+    if (p.taxId !== undefined) ops.push(set(org, "taxId", p.taxId));
+    if (p.address !== undefined) ops.push(set(org, "address", p.address));
+    return ops;
+  });
+
+// ── public user (profile index) ──────────────────────────────────────────────
+
+/** createPublicUser — .creates the PublicUser profile index entry. */
+export const createPublicUser = directive("createPublicUser")
+  .creates(PublicUser)
+  .payload(
+    z.object({
+      userId: z.string(),
+      email: z.string().email(),
+      displayName: z.string(),
+      photoUrl: z.string().optional(),
+      updatedAt: z.string(),
+    }),
+  )
+  .plan((p) => {
+    // #105: PublicUser is keyed by userId (v1 entityId = userId).
+    const pu = instance(PublicUser, p.userId);
+    const ops = [
+      set(pu, "userId", p.userId),
+      set(pu, "email", p.email),
+      set(pu, "displayName", p.displayName),
+      set(pu, "updatedAt", p.updatedAt),
+    ];
+    if (p.photoUrl !== undefined) ops.push(set(pu, "photoUrl", p.photoUrl));
+    return ops;
+  });
+
+/** updatePublicUserProfile — .mutates the PublicUser profile scalars. */
+export const updatePublicUserProfile = directive("updatePublicUserProfile")
+  .mutates(PublicUser)
+  .payload(
+    z.object({
+      userId: z.string(), // #105: target the concrete public-user instance (v1 keys on userId).
+      displayName: z.string().optional(),
+      photoUrl: z.string().optional(),
+      email: z.string().email().optional(),
+      updatedAt: z.string(),
+    }),
+  )
+  .plan((p) => {
+    const pu = instance(PublicUser, p.userId);
+    const ops = [] as ReturnType<typeof set>[];
+    if (p.displayName !== undefined) ops.push(set(pu, "displayName", p.displayName));
+    if (p.photoUrl !== undefined) ops.push(set(pu, "photoUrl", p.photoUrl));
+    if (p.email !== undefined) ops.push(set(pu, "email", p.email));
+    ops.push(set(pu, "updatedAt", p.updatedAt));
+    return ops;
+  });
+
+// ─────────────────────── FRAMEWORK / TENANT boundary ────────────────────────
+//
+// This module is now FRAMEWORK-ONLY: it carries the identity CORE aggregates
+// (Actor, User, DeviceKey, Organization, PublicUser) and their directives — no
+// tenant content. The tenant-specific identity aggregates that used to live here
+// have moved to the tenant package (its `the tenant identity module` module). The tenant engine
+// bundle MERGES this framework `identity` module with the tenant's identity module
+// under the SAME `identity` domain key, so the runtime dispatch is byte-for-byte
+// unchanged — the boundary moved, the wire contract did not.