@granular-software/sdk 0.4.12 → 0.4.14

package/dist/cli/index.js

@@ -10,6 +10,7 @@ var crypto = require('crypto');
 var process6 = require('process');
 var os = require('os');
 var tty = require('tty');
+var metamodelPresetDefault = require('@granular-software/metamodel-preset-default');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -3439,7 +3440,7 @@ var require_main = __commonJS({
     var os2 = __require("os");
     var crypto = __require("crypto");
     var packageJson = require_package();
-    var version = packageJson.version;
+    var version2 = packageJson.version;
     var LINE = /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg;
     function parse(src) {
       const obj = {};
@@ -3488,13 +3489,13 @@ var require_main = __commonJS({
       return DotenvModule.parse(decrypted);
     }
     function _warn(message) {
-      console.log(`[dotenv@${version}][WARN] ${message}`);
+      console.log(`[dotenv@${version2}][WARN] ${message}`);
     }
     function _debug(message) {
-      console.log(`[dotenv@${version}][DEBUG] ${message}`);
+      console.log(`[dotenv@${version2}][DEBUG] ${message}`);
     }
     function _log(message) {
-      console.log(`[dotenv@${version}] ${message}`);
+      console.log(`[dotenv@${version2}] ${message}`);
     }
     function _dotenvKey(options) {
       if (options && options.DOTENV_KEY && options.DOTENV_KEY.length > 0) {
@@ -6529,7 +6530,8 @@ async function main() {
 
   // Connect as one app user so the SDK can create an environment for the seed run.
   const env = await granular.connect({
-    sandbox: SANDBOX_ID,
+    ontology: SANDBOX_ID,
+    environment: 'dev',
     userId: '${template.seedUser.userId}',
     name: '${template.seedUser.name}',
     email: '${template.seedUser.email}',
@@ -6865,15 +6867,72 @@ var ApiClient = class {
     );
     return result.items;
   }
+  async listVersions(sandboxId) {
+    const result = await this.request(
+      `/control/sandboxes/${sandboxId}/versions`
+    );
+    return result.items;
+  }
   async getBuild(buildId) {
     return this.request(`/control/builds/${buildId}`);
   }
+  async getVersion(versionId) {
+    return this.request(`/control/versions/${versionId}`);
+  }
   async triggerBuild(sandboxId, manifestId) {
     return this.request(`/control/sandboxes/${sandboxId}/builds`, {
       method: "POST",
       body: JSON.stringify({ manifestId })
     });
   }
+  async createVersion(sandboxId, manifestId) {
+    return this.triggerBuild(sandboxId, manifestId);
+  }
+  async listTags(sandboxId) {
+    const result = await this.request(
+      `/control/sandboxes/${sandboxId}/tags`
+    );
+    return result.items.map((tag2) => ({
+      ...tag2,
+      targetVersionId: tag2.targetVersionId ?? tag2.targetBuildId ?? null
+    }));
+  }
+  async moveTag(tagId, targetBuildId) {
+    const moved = await this.request(`/control/tags/${tagId}/move`, {
+      method: "POST",
+      body: JSON.stringify({ targetBuildId })
+    });
+    return {
+      ...moved,
+      targetVersionId: moved.targetVersionId ?? moved.targetBuildId ?? null
+    };
+  }
+  async moveVersionTag(tagId, targetVersionId) {
+    return this.moveTag(tagId, targetVersionId);
+  }
+  async promoteToProd(buildId) {
+    return this.request(`/control/builds/${buildId}/promote`, {
+      method: "POST"
+    });
+  }
+  async promoteVersionToProd(versionId) {
+    return this.request(`/control/versions/${versionId}/promote`, {
+      method: "POST"
+    });
+  }
+  async getBuildDiff(buildId, againstBuildId) {
+    const query = againstBuildId ? `?against=${encodeURIComponent(againstBuildId)}` : "";
+    return this.request(`/control/builds/${buildId}/diff${query}`);
+  }
+  async getVersionDiff(versionId, againstVersionId) {
+    const query = againstVersionId ? `?against=${encodeURIComponent(againstVersionId)}` : "";
+    const result = await this.request(`/control/versions/${versionId}/diff${query}`);
+    return {
+      versionId: result.buildId,
+      againstVersionId: result.againstBuildId,
+      diff: result.diff
+    };
+  }
   async waitForBuild(buildId, onStatus, timeoutMs = 12e4) {
     const start = Date.now();
     while (Date.now() - start < timeoutMs) {
@@ -6890,6 +6949,9 @@ var ApiClient = class {
     }
     throw new Error(`Build timed out after ${Math.round(timeoutMs / 1e3)}s`);
   }
+  async waitForVersionBuild(versionId, onStatus, timeoutMs = 12e4) {
+    return this.waitForBuild(versionId, onStatus, timeoutMs);
+  }
   // ── Permission Profiles ──
   async createPermissionProfile(sandboxId, data) {
     return this.request(
@@ -7541,10 +7603,10 @@ function _supportsColor(haveStream, { streamIsTTY, sniffFlags = true } = {}) {
     return 3;
   }
   if ("TERM_PROGRAM" in env) {
-    const version = Number.parseInt((env.TERM_PROGRAM_VERSION || "").split(".")[0], 10);
+    const version2 = Number.parseInt((env.TERM_PROGRAM_VERSION || "").split(".")[0], 10);
     switch (env.TERM_PROGRAM) {
       case "iTerm.app": {
-        return version >= 3 ? 3 : 2;
+        return version2 >= 3 ? 3 : 2;
       }
       case "Apple_Terminal": {
         return 2;
@@ -8594,7 +8656,7 @@ var brand = {
 function printHeader() {
   console.log();
   console.log(brand.primary.bold("  \u25A0 Granular"));
-  console.log(brand.muted("  Build AI sandboxes from code"));
+  console.log(brand.muted("  Version and run ontologies from code"));
   console.log();
 }
 function success(message) {
@@ -8776,10 +8838,11 @@ The rest of this guide assumes these terms.
 | Term | What it means |
 |------|----------------|
 | **Sandbox** | A **workspace** on Granular (\`sbx_\u2026\`). It stores the **compiled domain** and **your records** for one project/environment. Not a browser sandbox \u2014 think \u201Ctenant + schema + data\u201D for this app. |
-| **Domain** | The **ontology**: **classes**, **relationships**, and **effects**. Declared in \`granular.json\`, installed on the sandbox by **build**. Same idea as *schema* / *model*. |
-| **Manifest** | \`granular.json\` (definition under \`manifest\`). **Source** in the repo until you **build**. |
-| **Build** | \`granular build\` \u2014 uploads and compiles the manifest. Primary **validation**; fixes errors before relying on types. |
-| **Environment** | Return value of \`granular.connect({ sandbox, \u2026 })\`. Your **server-side** handle for \`recordObject\`, \`submitJob\`, \`graphql\`, etc., bound to one sandbox. |
+| **Domain** | The **ontology**: **classes**, **relationships**, and **effects**. Declared in \`granular.json\`, installed on the sandbox by creating a **version**. Same idea as *schema* / *model*. |
+| **Manifest** | \`granular.json\` (definition under \`manifest\`). **Source** in the repo until you create a new ontology **version** from it. |
+| **Version** | Immutable ontology state derived from one manifest revision. Tags like \`dev\` and \`prod\` point to versions. |
+| **Build run** | The CI-style compilation process. \`granular build\` creates or reuses the ontology version, then runs a build for it. |
+| **Environment** | Return value of \`granular.connect({ ontology, environment, \u2026 })\`. It is your **server-side** handle for \`recordObject\`, \`submitJob\`, \`graphql\`, etc., bound to one ontology environment slot. |
 | **Session** | SDK base type; \`Environment\` **extends** \`Session\`. Job/prompt APIs live on \`Session\`; you still use the **\`Environment\`** instance from \`connect()\` in normal apps. |
 | **Job** | Code string passed to \`environment.submitJob(code)\`. Runs in Granular\u2019s **sandbox runtime** with access to \`./sandbox-tools\` (generated classes + effect entrypoints). |
 | **Effect** | Declared with \`withEffect\`; **handler** registered with \`registerEffects\` in **your** process. Jobs invoke effects; handlers do IO outside Granular. |
@@ -8800,9 +8863,9 @@ function manifestGuideEndToEndSection() {
 | Step | Action | Outcome |
 |------|--------|---------|
 | 1 | Edit \`granular.json\` (\`manifest\` \u2192 \`volumes\` \u2192 \`operations\`) | Domain **source** in the repo |
-| 2 | \`granular build\` | Manifest **uploaded**; domain **compiled** for the configured sandbox; errors surface here |
+| 2 | \`granular build\` | Manifest **uploaded**; ontology version created or reused; build run compiles it; errors surface here |
 | 3 | (Optional) Run your **effects host** \u2014 e.g. \`npx tsx granular-effects.ts\` \u2014 calling \`registerEffects(sandboxId, \u2026)\` | Effect **handlers** attached in **your** process |
-| 4 | \`new Granular({ apiKey })\` then \`connect({ sandbox, userId, permissions })\` | **\`Environment\`** for that sandbox |
+| 4 | \`new Granular({ apiKey })\` then \`connect({ ontology, environment, userId, permissions })\` | **\`Environment\`** for that ontology environment slot |
 | 5 | \`recordObject\` / \`recordObjects\` | **Records** stored with correct fields and relationship keys |
 | 6 | \`submitJob(\`\u2026\`)\` with imports from \`./sandbox-tools\` | **Jobs** run; may call **effects** \u2192 your handlers execute and return results |
 
@@ -8814,8 +8877,10 @@ function sandboxDocMainConceptsSection() {
 | Term | One line |
 |------|----------|
 | **Sandbox** | Workspace \`sbx_\u2026\` \u2014 **domain** + **data** for this project. |
-| **Domain / ontology** | Classes + relationships + effects \u2014 **built** from \`granular.json\`. |
+| **Domain / ontology** | Classes + relationships + effects \u2014 materialized from versioned manifests. |
 | **Manifest** | \`granular.json\` \u2014 **source**; edit here, then \`granular build\`. |
+| **Version** | Immutable ontology state created from one manifest revision. |
+| **Build run** | Compilation run that validates and materializes a version. |
 | **Environment** | \`connect()\` result \u2014 **record**, **submitJob**, **graphql** for this sandbox. |
 | **Session** | Base type; \`Environment\` extends it (job APIs). |
 | **Job** | \`submitJob\` code using \`./sandbox-tools\`. |
@@ -8833,10 +8898,29 @@ function sandboxDocScopeSection(projectName) {
 
 If **syntax** or **Granular behavior** is unclear, use the manifest guide; use **this** file for **ontology facts** for **${projectName}**.`;
 }
+function getFieldMetamodelDocRows() {
+  return metamodelPresetDefault.collectMetamodelDocRows("fieldRows");
+}
+function getModelMetamodelDocRows() {
+  return metamodelPresetDefault.collectMetamodelDocRows("modelRows");
+}
+function getEffectMetamodelDocRows() {
+  return metamodelPresetDefault.collectMetamodelDocRows("effectRows");
+}
+function renderMetamodelDocTable(rows) {
+  return [
+    "| Key | Meaning |",
+    "|-----|---------|",
+    ...rows.map((row) => `| \`${row.key}\` | ${row.description} |`)
+  ].join("\n");
+}
 
 // src/cli/agent-docs/manifest-guide.ts
 function generateManifestAgentGuide(options) {
   const { projectName } = options;
+  const fieldMetamodelTable = renderMetamodelDocTable(getFieldMetamodelDocRows());
+  const modelMetamodelTable = renderMetamodelDocTable(getModelMetamodelDocRows());
+  const effectMetamodelTable = renderMetamodelDocTable(getEffectMetamodelDocRows());
   return `# Granular manifest guide (for coding agents)
 
 This guide is for **coding agents** who may have **no prior context on Granular**. It explains the product, core terms, how to **author** \`granular.json\`, **build** the domain, and use the SDK (\`connect\` \u2192 **environment**, \`recordObject\`, \`submitJob\`, **effects**). For **this repository\u2019s** exact class names, relationship keys, and effect payloads only, see [GRANULAR_SANDBOX.md](../GRANULAR_SANDBOX.md).
@@ -8942,6 +9026,66 @@ Each key under \`has\` is a **field name** on the class. Each value is a **field
 - Every scalar field should have \`"type": "..."\`.
 - Do **not** store links to other entities as opaque strings when you can use **relationships** (next section).
 
+### Field metamodels
+
+Scalar fields can carry lightweight metamodels directly in their field spec:
+
+\`\`\`json
+{
+  "create": "ticket",
+  "extends": "@std/class",
+  "note": "Ticket workflow object",
+  "stateMachines": [
+    {
+      "name": "lifecycle",
+      "entryState": "draft",
+      "states": ["draft", "active", { "name": "done", "isFinal": true }],
+      "finalStates": ["canceled"],
+      "transitions": [
+        { "name": "activate", "from": "draft", "to": "active" },
+        { "name": "complete", "from": "active", "to": "done" },
+        { "name": "cancel", "from": "draft", "to": "canceled" }
+      ]
+    }
+  ],
+  "has": {
+    "title": {
+      "type": "string",
+      "required": true,
+      "note": "Must use the canonical prefix",
+      "filterBy": true,
+      "validate": [
+        { "operator": "regex", "stringValue": "^TKT-[A-Z0-9-]+$" }
+      ]
+    },
+    "status": {
+      "type": "string",
+      "enum": {
+        "values": ["draft", "active", "done", "canceled"],
+        "message": "Invalid ticket status"
+      },
+      "filterBy": ["equal_to", "contains"]
+    },
+    "estimate": {
+      "type": "number",
+      "filterBy": true,
+      "validate": [
+        { "operator": "gt", "numberValue": 0 },
+        { "operator": "lt", "numberValue": 100 }
+      ]
+    }
+  }
+}
+\`\`\`
+
+Supported field metamodel keys:
+
+${fieldMetamodelTable}
+
+Supported model-level metamodel keys:
+
+${modelMetamodelTable}
+
 ---
 
 ## Operations: \`defineRelationship\` (model links precisely)
@@ -9023,10 +9167,54 @@ Example:
 | \`isStatic\` | \`true\` \u2192 static method; \`false\` or omit \u2192 **instance** method (handler receives the object **id** first). |
 | \`inputSchema\` / \`outputSchema\` | JSON Schema; used for codegen and validation. |
 
-**Lifecycle:** declare in manifest \u2192 \`granular build\` \u2192 implement handlers \u2192 \`granular.registerEffects(sandboxId, [...])\` \u2192 jobs call generated methods \u2192 your handler runs and returns the result to the job.
+**Lifecycle:** declare in manifest \u2192 \`granular build\` creates or reuses a version and runs the build \u2192 implement handlers \u2192 \`granular.registerEffects(sandboxId, [...])\` \u2192 jobs call generated methods \u2192 your handler runs and returns the result to the job.
 
 **Permissions:** \`connect({ permissions: [...] })\` assigns profiles (e.g. \`default\`) that can allow or deny which effects a user may call.
 
+### Effect metamodels
+
+Effects can declare runtime behaviors under \`withEffect.metamodels\`:
+
+\`\`\`json
+{
+  "withEffect": {
+    "name": "publish_ticket",
+    "attachedClass": "ticket",
+    "inputSchema": {
+      "type": "object",
+      "properties": { "audience": { "type": "string" } }
+    },
+    "outputSchema": {
+      "type": "object",
+      "properties": { "ok": { "type": "boolean" } }
+    },
+    "metamodels": {
+      "postCondition": {
+        "condition": "result.ok == true",
+        "description": "Publishing must report success"
+      },
+      "dryRun": {
+        "enabled": true,
+        "description": "Preview publishing before sending"
+      },
+      "reverse": {
+        "handler": "unpublish_ticket",
+        "description": "Undo a publication"
+      },
+      "approvalRequired": {
+        "required": true,
+        "reason": "Publishing is user-visible",
+        "mode": "confirm"
+      }
+    }
+  }
+}
+\`\`\`
+
+Supported effect metamodel keys:
+
+${effectMetamodelTable}
+
 ---
 
 ## IDs and labels
@@ -9048,7 +9236,7 @@ Example:
 |-----|---------|
 | \`new Granular({ apiKey, apiUrl?, endpointMode?, token?, tokenProvider?, \u2026 })\` | Auth. Env: \`GRANULAR_API_KEY\`, \`GRANULAR_API_URL\`, \`GRANULAR_ENDPOINT_MODE\`. |
 | \`recordUser({ userId, name?, email?, permissions? })\` | Upsert user for later \`connect\`. |
-| \`connect({ sandbox, userId?, granularId?, user?, permissions?, clientId?, initialHeap? })\` | Opens a session \u2192 **\`Environment\`**. |
+| \`connect({ ontology, environment, tagName?, userId?, granularId?, user?, permissions?, clientId?, initialHeap? })\` | Opens a session \u2192 **\`Environment\`**. \`tagName\` is an advanced override. |
 | \`registerEffects(sandboxId, effects)\` / \`registerEffect\` | Register handlers for manifest \`withEffect\` declarations. |
 | \`unregisterEffect\` / \`unregisterAllEffects\` / \`disconnectEffects\` | Stop effect handlers for a sandbox. |
 | \`granular.sandboxes\` | \`.list()\`, \`.get\`, \`.create\`, \`.update\`, \`.delete\` |
@@ -9090,14 +9278,17 @@ Use \`environment.graphql(query, variables?)\` when you need **query/mutation ac
 
 | Command | Purpose |
 |---------|---------|
-| \`granular build\` | Upload \`granular.json\` and compile (primary **validation**). |
-| \`granular deploy\` | Build + deploy current production. |
+| \`granular build\` | Upload \`granular.json\`, create or reuse the matching ontology version, and run the build (**validation**). |
+| \`granular deploy\` | Push the current revision, build it, and update \`dev\`. |
+| \`granular deploy --prod\` | If the current version is already on \`dev\`, also point \`prod\` to it. Otherwise build it, then point both \`dev\` and \`prod\` to it. |
+| \`granular version diff\` | Show the semantic diff between ontology versions. |
+| \`granular tag move\` | Move \`dev\`, \`prod\`, or another tag to a chosen version. |
 | \`granular dev\` | Watch manifest, rebuild on change. |
 | \`granular document\` | Regenerate \`GRANULAR_SANDBOX.md\`. |
 | \`granular init\` | Scaffold project; optional \`--agent-docs\`. |
 | \`granular add class|field|relation\` | Mutate local manifest. |
 | \`granular simulate\` | Open simulator in browser. |
-| \`granular pull\` | Pull manifest from API. |
+| \`granular pull <version>\` | Pull the manifest for a specific ontology version. |
 | \`granular login\`, \`granular whoami\`, \`granular status\` | Auth / project info. |
 
 ---
@@ -9106,7 +9297,7 @@ Use \`environment.graphql(query, variables?)\` when you need **query/mutation ac
 
 1. \`granular build\` (or \`granular dev\`).
 2. Align **effect handlers** with every \`withEffect\` name + schemas.
-3. \`granular document\` to refresh \`GRANULAR_SANDBOX.md\` without a full build if needed (build still records manifest/build ids).
+3. \`granular document\` to refresh \`GRANULAR_SANDBOX.md\` without a full build if needed (the last successful version/build metadata still comes from \`granular build\` or \`granular deploy\`).
 
 ---
 
@@ -9191,9 +9382,9 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push(`| Sandbox id | \`${meta.sandboxId}\` |`);
   if (meta.apiUrl) lines.push(`| API / WS base | \`${meta.apiUrl}\` |`);
   if (meta.manifestId) lines.push(`| Last uploaded manifest id | \`${meta.manifestId}\` |`);
-  if (meta.buildId) lines.push(`| Last build id | \`${meta.buildId}\` |`);
+  if (meta.buildId) lines.push(`| Last version id | \`${meta.buildId}\` |`);
   if (meta.buildPending) {
-    lines.push("| Build status | *No successful build recorded in this doc run \u2014 run `granular build`.* |");
+    lines.push("| Version status | *No successful version/build recorded in this doc run \u2014 run `granular build`.* |");
   }
   lines.push("");
   lines.push("Set `GRANULAR_API_KEY` (e.g. in `.env.local`). Optional: `GRANULAR_API_URL` overrides the WebSocket URL.");
@@ -9210,7 +9401,9 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push("");
   lines.push("| Command | Purpose |");
   lines.push("|---------|---------|");
-  lines.push("| `granular build` | Upload manifest and build |");
+  lines.push("| `granular build` | Create or rebuild the current ontology version |");
+  lines.push("| `granular version diff <version> [base]` | Show the semantic diff between versions |");
+  lines.push("| `granular tag move <tag> <version>` | Move a release tag such as `prod` |");
   lines.push("| `granular document` | Refresh this file from `granular.json` |");
   lines.push("| `npx tsx " + seed + "` | Seed sample records (if present) |");
   lines.push("| `npx tsx " + eff + "` | Run effect handler host (if present) |");
@@ -9226,7 +9419,8 @@ function generateSandboxAgentDoc(manifest, meta) {
   lines.push(`});`);
   lines.push("");
   lines.push(`const env = await granular.connect({`);
-  lines.push(`  sandbox: '${meta.sandboxId}',`);
+  lines.push(`  ontology: '${meta.sandboxId}',`);
+  lines.push(`  environment: 'dev',`);
   lines.push(`  userId: 'your_app_user_id',`);
   lines.push(`  permissions: ['default'],`);
   lines.push(`});`);
@@ -9835,7 +10029,7 @@ async function loginCommand(options = {}) {
 }
 
 // src/cli/commands/pull.ts
-async function pullCommand() {
+async function pullCommand(versionId) {
   printHeader();
   const config = resolveConfig({ requireApiKey: true });
   if (!config.sandboxId) {
@@ -9843,17 +10037,13 @@ async function pullCommand() {
     process.exit(1);
   }
   const api = new ApiClient(config.apiKey, config.apiUrl);
-  const spin = spinner("Fetching manifests...");
+  const spin = spinner(`Fetching version ${versionId}...`);
   try {
-    const manifests = await api.listManifests(config.sandboxId);
-    if (manifests.length === 0) {
-      spin.fail("  No manifests found for this sandbox.");
-      hint("granular build", "Upload and build your local manifest");
-      return;
-    }
-    const latest = manifests[0];
+    const version2 = await api.getVersion(versionId);
+    const targetManifestId = version2.manifestId;
+    const targetVersionLabel = version2.versionNumber != null ? `v${version2.versionNumber}` : versionId;
     spin.text = "  Downloading manifest content...";
-    const full = await api.getManifest(latest.manifestId);
+    const full = await api.getManifest(targetManifestId);
     if (!full.content) {
       spin.fail("  Manifest has no content.");
       return;
@@ -9865,8 +10055,9 @@ async function pullCommand() {
     spin.succeed("  Manifest pulled successfully.");
     console.log();
     keyValue({
-      "Manifest ID": latest.manifestId,
-      "Version": latest.version || "N/A",
+      "Manifest ID": full.manifestId,
+      "Source Version": versionId,
+      "Version": targetVersionLabel,
       "Written to": "granular.json"
     });
     console.log();
@@ -9895,17 +10086,23 @@ async function buildCommand() {
     uploading.fail(`  Failed to upload manifest: ${err.message}`);
     process.exit(1);
   }
-  const building = spinner("Triggering build...");
+  const building = spinner("Creating or reusing ontology version from manifest...");
   try {
-    const build = await api.triggerBuild(config.sandboxId, uploadedManifest.manifestId);
-    building.text = `  Building... ${brand.muted(build.buildId)}`;
+    const version2 = await api.createVersion(config.sandboxId, uploadedManifest.manifestId);
+    building.text = `  Running build for version... ${brand.muted(version2.buildId)}`;
     const startTime = Date.now();
-    const completed = await api.waitForBuild(build.buildId, (status) => {
+    const completed = await api.waitForVersionBuild(version2.buildId, (status) => {
       const elapsed = Math.round((Date.now() - startTime) / 1e3);
-      building.text = `  Building... ${brand.muted(`${status} (${elapsed}s)`)}`;
+      building.text = `  Running build for version... ${brand.muted(`${status} (${elapsed}s)`)}`;
     });
     const totalTime = Math.round((Date.now() - startTime) / 1e3);
-    building.succeed(`  Build completed in ${totalTime}s`);
+    building.succeed(`  Version ready in ${totalTime}s`);
+    const [tags, diff] = await Promise.all([
+      api.listTags(config.sandboxId),
+      api.getVersionDiff(completed.buildId).catch(() => null)
+    ]);
+    const devTag = tags.find((tag2) => tag2.name === "dev");
+    const prodTag = tags.find((tag2) => tag2.name === "prod");
     writeSandboxAgentDocFile(getProjectRoot(), manifest, {
       sandboxId: config.sandboxId,
       apiUrl: config.apiUrl,
@@ -9914,12 +10111,27 @@ async function buildCommand() {
     });
     console.log();
     keyValue({
-      "Build ID": completed.buildId,
+      "Version ID": completed.buildId,
+      "Version Number": completed.versionNumber != null ? String(completed.versionNumber) : "N/A",
+      "Build Run": completed.buildRunId || completed.latestBuildRunId || "N/A",
       "Manifest": uploadedManifest.manifestId,
-      "Status": "completed",
+      "Result": completed.createdNewVersion ? "new version created" : "existing version reused, new build run recorded",
+      "Dev Tag": devTag?.targetVersionId === completed.buildId || devTag?.targetBuildId === completed.buildId ? "updated to this version" : devTag?.targetVersionId || devTag?.targetBuildId || "not set",
+      "Prod Tag": prodTag?.targetVersionId || prodTag?.targetBuildId || "not set",
       "Duration": `${totalTime}s`,
       "Agent doc": "GRANULAR_SANDBOX.md"
     });
+    if (diff?.diff?.summary) {
+      console.log();
+      keyValue({
+        "Diff Added": String(diff.diff.summary.added ?? 0),
+        "Diff Changed": String(diff.diff.summary.changed ?? 0),
+        "Diff Removed": String(diff.diff.summary.removed ?? 0),
+        "Transition Safety": diff.diff.summary.onlyAdditiveChanges ? "additive" : "breaking changes detected"
+      });
+    }
+    console.log();
+    info("Common path: keep working in your dev environment while dev follows the newest successful version. Prod only changes when you promote it.");
     console.log();
   } catch (err) {
     building.fail(`  Build failed: ${err.message}`);
@@ -9928,7 +10140,7 @@ async function buildCommand() {
 }
 
 // src/cli/commands/deploy.ts
-async function deployCommand() {
+async function deployCommand(options = {}) {
   printHeader();
   const config = resolveConfig({ requireApiKey: true, requireProject: true });
   if (!config.sandboxId) {
@@ -9936,7 +10148,7 @@ async function deployCommand() {
     process.exit(1);
   }
   const api = new ApiClient(config.apiKey, config.apiUrl);
-  step("Deploy", `Sandbox ${config.sandboxId}`);
+  step(options.prod ? "Deploy to dev and prod" : "Deploy to dev", `Sandbox ${config.sandboxId}`);
   console.log();
   const manifest = config.project.manifest;
   const uploading = spinner(`Uploading manifest "${manifest.name}"...`);
@@ -9948,16 +10160,45 @@ async function deployCommand() {
     uploading.fail(`  Failed to upload manifest: ${err.message}`);
     process.exit(1);
   }
-  const building = spinner("Building...");
+  const building = spinner("Resolving ontology version from manifest...");
   try {
-    const build = await api.triggerBuild(config.sandboxId, uploadedManifest.manifestId);
-    const startTime = Date.now();
-    const completed = await api.waitForBuild(build.buildId, (status) => {
-      const elapsed = Math.round((Date.now() - startTime) / 1e3);
-      building.text = `  Building... ${brand.muted(`${status} (${elapsed}s)`)}`;
-    });
-    const totalTime = Math.round((Date.now() - startTime) / 1e3);
-    building.succeed(`  Build completed in ${totalTime}s`);
+    const [versions, tags] = await Promise.all([
+      api.listVersions(config.sandboxId),
+      api.listTags(config.sandboxId).catch(() => [])
+    ]);
+    const devTag = tags.find((tag2) => tag2.name === "dev");
+    const prodTag = tags.find((tag2) => tag2.name === "prod");
+    const existingVersion = versions.find((version2) => version2.manifestDigest === uploadedManifest.digest) || null;
+    const existingVersionId = existingVersion?.buildId || null;
+    const devVersionId = devTag?.targetVersionId || devTag?.targetBuildId || null;
+    const reuseDevPromotion = Boolean(
+      options.prod && existingVersion && existingVersion.status === "completed" && existingVersionId && devVersionId === existingVersionId
+    );
+    let completed = existingVersion;
+    let totalTime = 0;
+    let deployedToDev = false;
+    if (reuseDevPromotion) {
+      building.succeed(`  Current manifest already matches ${brand.secondary(existingVersionId)} on dev.`);
+    } else {
+      const version2 = await api.createVersion(config.sandboxId, uploadedManifest.manifestId);
+      const startTime = Date.now();
+      building.text = `  Running build for version... ${brand.muted(version2.buildId)}`;
+      completed = await api.waitForVersionBuild(version2.buildId, (status) => {
+        const elapsed = Math.round((Date.now() - startTime) / 1e3);
+        building.text = `  Running build for version... ${brand.muted(`${status} (${elapsed}s)`)}`;
+      });
+      totalTime = Math.round((Date.now() - startTime) / 1e3);
+      deployedToDev = true;
+      building.succeed(`  Dev now points to ${brand.secondary(completed.buildId)} (${totalTime}s)`);
+    }
+    if (!completed) {
+      throw new Error("Could not resolve the current ontology version.");
+    }
+    if (options.prod) {
+      const promoting = spinner("Promoting prod...");
+      await api.promoteVersionToProd(completed.buildId);
+      promoting.succeed(`  Prod now points to ${brand.secondary(completed.buildId)}`);
+    }
     writeSandboxAgentDocFile(getProjectRoot(), manifest, {
       sandboxId: config.sandboxId,
       apiUrl: config.apiUrl,
@@ -9968,12 +10209,20 @@ async function deployCommand() {
     success(`Deployed ${brand.bold(manifest.name)} successfully!`);
     console.log();
     keyValue({
-      "Build": completed.buildId,
+      "Version": completed.buildId,
+      "Version Number": completed.versionNumber != null ? String(completed.versionNumber) : "N/A",
+      "Build Run": completed.buildRunId || completed.latestBuildRunId || "N/A",
       "Manifest": uploadedManifest.manifestId,
-      "Status": "live",
+      "Dev Tag": completed.buildId,
+      "Prod Tag": options.prod ? completed.buildId : prodTag?.targetVersionId || prodTag?.targetBuildId || "unchanged",
+      "Release": options.prod ? deployedToDev ? "dev and prod now point to this version" : "prod promoted to the version already on dev" : "dev updated to this version",
       "Agent doc": "GRANULAR_SANDBOX.md"
     });
     console.log();
+    if (options.prod) {
+      info("Existing prod environments keep their current version until they are transitioned.");
+      console.log();
+    }
   } catch (err) {
     building.fail(`  Deploy failed: ${err.message}`);
     process.exit(1);
@@ -10001,21 +10250,30 @@ async function statusCommand() {
       "Created": sandbox.createdAt
     });
     console.log();
-    const builds = await api.listBuilds(config.sandboxId);
+    const builds = await api.listVersions(config.sandboxId);
+    const tags = await api.listTags(config.sandboxId).catch(() => []);
+    const devTag = tags.find((tag2) => tag2.name === "dev");
+    const prodTag = tags.find((tag2) => tag2.name === "prod");
+    keyValue({
+      "Dev Version": devTag?.targetVersionId || devTag?.targetBuildId || "not set",
+      "Prod Version": prodTag?.targetVersionId || prodTag?.targetBuildId || "not set"
+    });
+    console.log();
     if (builds.length > 0) {
-      step("Recent Builds");
+      step("Recent Versions");
       console.log();
       const recentBuilds = builds.slice(0, 5);
       table(
-        ["Build ID", "Status", "Created"],
+        ["Version", "Status", "Users/Envs", "Created"],
         recentBuilds.map((b) => [
           b.buildId,
           buildStatus(b.status),
+          `${b.environmentCount ?? 0}/${b.sessionCount ?? 0}`,
           b.createdAt ? String(b.createdAt) : "N/A"
         ])
       );
     } else {
-      dim("No builds yet. Run `granular build` to create one.");
+      dim("No versions yet. Run `granular build` to create one.");
     }
     console.log();
     const manifests = await api.listManifests(config.sandboxId);
@@ -10357,18 +10615,145 @@ async function simulateCommand(sandboxIdArg, options) {
   openUrl(url);
 }
 
+// src/cli/commands/version.ts
+function formatVersionLabel(versionId, versionNumber) {
+  return versionNumber != null ? `v${versionNumber}` : versionId;
+}
+async function versionDiffCommand(versionId, againstVersionId) {
+  printHeader();
+  const config = resolveConfig({ requireApiKey: true });
+  const api = new ApiClient(config.apiKey, config.apiUrl);
+  const spin = spinner(
+    againstVersionId ? `Computing diff ${versionId} \u2190 ${againstVersionId}...` : `Computing diff for ${versionId}...`
+  );
+  try {
+    const [version2, diffResult] = await Promise.all([
+      api.getVersion(versionId),
+      api.getVersionDiff(versionId, againstVersionId)
+    ]);
+    const baseVersion = diffResult.againstVersionId ? await api.getVersion(diffResult.againstVersionId).catch(() => null) : null;
+    const summary = diffResult.diff.summary;
+    spin.succeed("  Version diff ready.");
+    console.log();
+    keyValue({
+      "Version": formatVersionLabel(version2.buildId, version2.versionNumber),
+      "Compared against": baseVersion ? formatVersionLabel(baseVersion.buildId, baseVersion.versionNumber) : diffResult.againstVersionId || "previous version",
+      "Added operations": summary.added,
+      "Changed operations": summary.changed,
+      "Removed operations": summary.removed,
+      "Transition safety": summary.onlyAdditiveChanges ? "additive only" : "breaking changes detected"
+    });
+    if (diffResult.diff.entries.length === 0) {
+      console.log();
+      info("No ontology changes between these versions.");
+      console.log();
+      return;
+    }
+    console.log();
+    step("Semantic diff");
+    console.log();
+    table(
+      ["Change", "Kind", "Operation", "Safety"],
+      diffResult.diff.entries.map((entry) => [
+        entry.changeType,
+        entry.kind,
+        entry.label,
+        entry.additive ? "safe-add" : "breaking"
+      ])
+    );
+    console.log();
+  } catch (err) {
+    spin.fail(`  Failed to compute diff: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// src/cli/commands/tag.ts
+function renderVersionTarget(versionId) {
+  if (!versionId) return "not set";
+  return versionId;
+}
+async function tagListCommand() {
+  printHeader();
+  const config = resolveConfig({ requireApiKey: true });
+  if (!config.sandboxId) {
+    error("No ontology configured. Run `granular init` first.");
+    process.exit(1);
+  }
+  const api = new ApiClient(config.apiKey, config.apiUrl);
+  const spin = spinner("Loading tags...");
+  try {
+    const tags = await api.listTags(config.sandboxId);
+    spin.succeed("  Tags loaded.");
+    console.log();
+    if (tags.length === 0) {
+      dim("No tags defined for this ontology yet.");
+      console.log();
+      return;
+    }
+    table(
+      ["Tag", "Target version", "Kind", "Protected"],
+      tags.map((tag2) => [
+        tag2.name,
+        renderVersionTarget(tag2.targetVersionId || tag2.targetBuildId),
+        tag2.kind,
+        tag2.protected ? "yes" : "no"
+      ])
+    );
+    console.log();
+  } catch (err) {
+    spin.fail(`  Failed to load tags: ${err.message}`);
+    process.exit(1);
+  }
+}
+async function tagMoveCommand(tagName, versionId) {
+  printHeader();
+  const config = resolveConfig({ requireApiKey: true });
+  if (!config.sandboxId) {
+    error("No ontology configured. Run `granular init` first.");
+    process.exit(1);
+  }
+  const api = new ApiClient(config.apiKey, config.apiUrl);
+  const spin = spinner(`Moving ${tagName} to version ${versionId}...`);
+  try {
+    const tags = await api.listTags(config.sandboxId);
+    const tag2 = tags.find((candidate) => candidate.name === tagName);
+    if (!tag2) {
+      spin.fail(`  Tag "${tagName}" was not found for this ontology.`);
+      process.exit(1);
+    }
+    const previousVersionId = tag2.targetVersionId || tag2.targetBuildId || null;
+    const moved = await api.moveVersionTag(tag2.tagId, versionId);
+    spin.succeed(`  ${tagName} now points to ${versionId}.`);
+    console.log();
+    keyValue({
+      "Tag": moved.name,
+      "Previous version": previousVersionId || "not set",
+      "Current version": moved.targetVersionId || moved.targetBuildId || "not set",
+      "Protected": moved.protected ? "yes" : "no"
+    });
+    console.log();
+    if (moved.name === "prod") {
+      info("Existing prod environments keep their current version until they are transitioned.");
+      console.log();
+    } else if (moved.name === "dev") {
+      info("dev is usually automatic. You only need to move it manually for exceptional release workflows.");
+      console.log();
+    }
+  } catch (err) {
+    spin.fail(`  Failed to move tag: ${err.message}`);
+    process.exit(1);
+  }
+}
+
 // src/cli/index.ts
 var VERSION = "0.2.0";
 var program2 = new Command();
-program2.name("granular").description("Build and deploy AI sandboxes from code").version(VERSION, "-v, --version");
-program2.option("--local", "Use local endpoints (localhost)").option("--prod", "Use production endpoints").option("--env <target>", "Endpoint target: local|production");
+program2.name("granular").description("Version and run Granular ontologies from code").version(VERSION, "-v, --version");
+program2.option("--local", "Use local endpoints (localhost)").option("--env <target>", "Endpoint target: local|production");
 program2.hook("preAction", () => {
   const opts = program2.opts();
   const normalizedEnv = opts.env?.trim().toLowerCase();
-  if (opts.local && opts.prod) {
-    error("Cannot use --local and --prod at the same time.");
-    process.exit(1);
-  }
   if (normalizedEnv && !["local", "production", "prod"].includes(normalizedEnv)) {
     error('Invalid --env value. Use "local" or "production".');
     process.exit(1);
@@ -10376,7 +10761,7 @@ program2.hook("preAction", () => {
   let mode;
   if (opts.local || normalizedEnv === "local") {
     mode = "local";
-  } else if (opts.prod || normalizedEnv === "production" || normalizedEnv === "prod") {
+  } else if (normalizedEnv === "production" || normalizedEnv === "prod") {
     mode = "production";
   }
   if (mode) {
@@ -10411,15 +10796,15 @@ program2.command("login").description("Authenticate with Granular (browser by de
     process.exit(1);
   }
 });
-program2.command("pull").description("Pull the latest manifest from the API").action(async () => {
+program2.command("pull <version-id>").description("Pull the manifest for a specific ontology version").action(async (versionId) => {
   try {
-    await pullCommand();
+    await pullCommand(versionId);
   } catch (err) {
     error(err.message);
     process.exit(1);
   }
 });
-program2.command("build").description("Upload manifest and trigger a build").action(async () => {
+program2.command("build").description("Create or reuse the ontology version for your current manifest, then run its build").action(async () => {
   try {
     await buildCommand();
   } catch (err) {
@@ -10427,15 +10812,15 @@ program2.command("build").description("Upload manifest and trigger a build").act
     process.exit(1);
   }
 });
-program2.command("deploy").description("Build and deploy as the current production version").action(async () => {
+program2.command("deploy").description("Push the current revision to dev; use --prod to move prod there too").option("--prod", "Also point prod to the current version").action(async (opts) => {
   try {
-    await deployCommand();
+    await deployCommand({ prod: opts.prod });
   } catch (err) {
     error(err.message);
     process.exit(1);
   }
 });
-program2.command("status").description("Show sandbox and build status").action(async () => {
+program2.command("status").description("Show ontology versions, dev/prod, and manifest status").action(async () => {
   try {
     await statusCommand();
   } catch (err) {
@@ -10443,6 +10828,32 @@ program2.command("status").description("Show sandbox and build status").action(a
     process.exit(1);
   }
 });
+var version = program2.command("version").description("Inspect ontology versions");
+version.command("diff <version-id> [against-version-id]").description("Show the semantic diff between one version and another").action(async (versionId, againstVersionId) => {
+  try {
+    await versionDiffCommand(versionId, againstVersionId);
+  } catch (err) {
+    error(err.message);
+    process.exit(1);
+  }
+});
+var tag = program2.command("tag").description("Inspect and move release tags such as dev and prod");
+tag.command("list").description("List tags for the current ontology").action(async () => {
+  try {
+    await tagListCommand();
+  } catch (err) {
+    error(err.message);
+    process.exit(1);
+  }
+});
+tag.command("move <tag-name> <version-id>").description("Move a tag to a specific ontology version").action(async (tagName, versionId) => {
+  try {
+    await tagMoveCommand(tagName, versionId);
+  } catch (err) {
+    error(err.message);
+    process.exit(1);
+  }
+});
 var add = program2.command("add").description("Add schema elements to the local manifest");
 add.command("class <name>").description("Add a new class to the schema").action(async (name) => {
   try {