@granular-software/sdk 0.4.69 → 0.4.71

package/dist/index.js

@@ -4300,8 +4300,8 @@ function normalizeFeedItems(values) {
   return { items: Object.freeze(items), error };
 }
 function normalizeTransients(values) {
-  const record = asRecord(values);
-  if (!record) {
+  const record2 = asRecord(values);
+  if (!record2) {
     return {
       items: [],
       error: new Error("Canonical feed transientById is not an object.")
@@ -4310,7 +4310,7 @@ function normalizeTransients(values) {
   let error = null;
   const byId = /* @__PURE__ */ new Map();
   const idByOrdinal = /* @__PURE__ */ new Map();
-  for (const [key, value] of Object.entries(record)) {
+  for (const [key, value] of Object.entries(record2)) {
     const item = normalizeTransientFeedItem(value);
     if (!item || item.id !== key) {
       error ||= new Error("Canonical feed contains an invalid transient item.");
@@ -5183,11 +5183,11 @@ function operationId(prefix) {
   return randomUuid ? `${prefix}_${randomUuid}` : `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
 }
 function unwrapPublishedItem(value) {
-  const record = asRecord(value);
-  const directItems = Array.isArray(record?.items) ? record.items : [];
-  const durable = asRecord(record?.durable);
+  const record2 = asRecord(value);
+  const directItems = Array.isArray(record2?.items) ? record2.items : [];
+  const durable = asRecord(record2?.durable);
   const durableItems = Array.isArray(durable?.items) ? durable.items : [];
-  return record?.item || directItems[0] || durableItems[0] || value;
+  return record2?.item || directItems[0] || durableItems[0] || value;
 }
 function requireFeedbackItem(value) {
   const item = normalizeFeedItem(unwrapPublishedItem(value));
@@ -5227,14 +5227,14 @@ function createFeedPublisher(publish) {
       get revision() {
         return current.revision;
       },
-      update(text, options = {}) {
+      update(text2, options = {}) {
         const reservedOperationId = options.operationId || operationId("feed_transient_update");
         const reservedOptions = { ...options };
         return enqueueMutation(async () => {
           const response = await publish("feed.transient.update", {
             transientId: current.id,
             expectedRevision: current.revision,
-            text,
+            text: text2,
             ...reservedOptions,
             operationId: reservedOperationId
           });
@@ -5242,14 +5242,14 @@ function createFeedPublisher(publish) {
           return handle;
         });
       },
-      settle(text, options = {}) {
+      settle(text2, options = {}) {
         const reservedOperationId = options.operationId || operationId("feed_transient_settle");
         const reservedOptions = { ...options };
         return enqueueMutation(async () => {
           const response = await publish("feed.transient.settle", {
             transientId: current.id,
             expectedRevision: current.revision,
-            ...text === void 0 ? {} : { text },
+            ...text2 === void 0 ? {} : { text: text2 },
             ...reservedOptions,
             operationId: reservedOperationId
           });
@@ -5267,19 +5267,19 @@ function createFeedPublisher(publish) {
     return handle;
   };
   return {
-    async feedback(text, options = {}) {
+    async feedback(text2, options = {}) {
       return requireFeedbackItem(
         await publish("feed.feedback", {
-          text,
+          text: text2,
           ...options,
           operationId: options.operationId || operationId("feed_feedback")
         })
       );
     },
-    async transientFeedback(text, options = {}) {
+    async transientFeedback(text2, options = {}) {
       const item = requireTransientFeedbackItem(
         await publish("feed.transient.create", {
-          text,
+          text: text2,
           ...options,
           operationId: options.operationId || operationId("feed_transient_create")
         })
@@ -5309,9 +5309,9 @@ var DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
 var DOCUMENT_RESYNC_CLOSE_CODE = 4e3;
 var DOCUMENT_RESYNC_CLOSE_REASON = "Document resync required";
 function documentVersion(document) {
-  const record = document;
-  const epochValue = record.documentEpoch;
-  const revisionValue = record.documentRevision;
+  const record2 = document;
+  const epochValue = record2.documentEpoch;
+  const revisionValue = record2.documentRevision;
   const epoch = epochValue === void 0 ? 0 : epochValue;
   const revision = revisionValue === void 0 ? 0 : revisionValue;
   if (!Number.isSafeInteger(epoch) || Number(epoch) < 0 || !Number.isSafeInteger(revision) || Number(revision) < 0) {
@@ -5333,11 +5333,43 @@ function stableDocumentFingerprint(value) {
   if (Array.isArray(value)) {
     return `[${value.map(stableDocumentFingerprint).join(",")}]`;
   }
-  const record = value;
-  return `{${Object.keys(record).sort().map(
-    (key) => `${JSON.stringify(key)}:${stableDocumentFingerprint(record[key])}`
+  const record2 = value;
+  return `{${Object.keys(record2).sort().map(
+    (key) => `${JSON.stringify(key)}:${stableDocumentFingerprint(record2[key])}`
   ).join(",")}}`;
 }
+function canonicalDocumentFingerprint(value) {
+  const stripPresentation = (input, path) => {
+    if (input === null || typeof input !== "object") return input;
+    if (input instanceof Date || input instanceof Uint8Array) return input;
+    if (Array.isArray(input)) {
+      return input.map((entry) => stripPresentation(entry, path));
+    }
+    const record2 = input;
+    const output = {};
+    for (const [key, entry] of Object.entries(record2)) {
+      if (path.length === 1 && path[0] === "feed" && [
+        "transientById",
+        "feedbackUsageByJob",
+        "revision",
+        "lastTransientOrdinal"
+      ].includes(key)) {
+        continue;
+      }
+      if (path.length === 3 && path[0] === "jobs" && path[1] === "byId" && [
+        "actionTrace",
+        "actionSummary",
+        "actionSummaryText",
+        "lastActionAt"
+      ].includes(key)) {
+        continue;
+      }
+      output[key] = stripPresentation(entry, [...path, key]);
+    }
+    return output;
+  };
+  return stableDocumentFingerprint(stripPresentation(value, []));
+}
 function debugWs(...args) {
   if (DEBUG_WS) {
     console.log(...args);
@@ -5655,6 +5687,7 @@ var WSClient = class {
         }
         this.lastInboundActivityAt = Date.now();
         this.reconnectAttempts = 0;
+        this.connectPromise = null;
         this.emit("open", {});
         finish();
       };
@@ -5662,8 +5695,8 @@ var WSClient = class {
         if (!isCurrent()) return;
         this.lastInboundActivityAt = Date.now();
         try {
-          const text = typeof data === "string" ? data : data && typeof data === "object" && "toString" in data ? String(data.toString()) : "";
-          this.handleMessage(JSON.parse(text));
+          const text2 = typeof data === "string" ? data : data && typeof data === "object" && "toString" in data ? String(data.toString()) : "";
+          this.handleMessage(JSON.parse(text2));
         } catch (error) {
           console.error("[Granular] Failed to parse message:", error);
         }
@@ -5721,8 +5754,8 @@ var WSClient = class {
     if (typeof reason === "string") return reason;
     if (typeof reason === "object" && reason && "toString" in reason) {
       try {
-        const text = String(reason.toString());
-        return text || void 0;
+        const text2 = String(reason.toString());
+        return text2 || void 0;
       } catch {
         return void 0;
       }
@@ -5817,7 +5850,7 @@ var WSClient = class {
       this.canonicalDocumentActivated = true;
     }
   }
-  canAcceptDocumentReplacement(replacement, strictlyNewer) {
+  canAcceptDocumentReplacement(replacement, strictlyNewer, options = {}) {
     const replacementCanonical = isCanonicalSessionFeedDocument(replacement);
     const currentCanonical = isCanonicalSessionFeedDocument(this.doc);
     if (replacementCanonical) {
@@ -5866,7 +5899,7 @@ var WSClient = class {
       debugWs(`[Granular DEBUG] Rejected session snapshot: ${canonicalError}`);
       return false;
     }
-    if (this.canonicalDocumentActivated && incoming.epoch === current.epoch && incoming.revision === current.revision && !readSessionFeedSnapshot(this.doc).error && stableDocumentFingerprint(Automerge__namespace.toJS(replacement)) !== stableDocumentFingerprint(Automerge__namespace.toJS(this.doc))) {
+    if (this.canonicalDocumentActivated && incoming.epoch === current.epoch && incoming.revision === current.revision && !readSessionFeedSnapshot(this.doc).error && (options.allowEqualRevisionPresentation ? canonicalDocumentFingerprint(Automerge__namespace.toJS(replacement)) : stableDocumentFingerprint(Automerge__namespace.toJS(replacement))) !== (options.allowEqualRevisionPresentation ? canonicalDocumentFingerprint(Automerge__namespace.toJS(this.doc)) : stableDocumentFingerprint(Automerge__namespace.toJS(this.doc)))) {
       debugWs(
         "[Granular DEBUG] Rejected divergent canonical snapshot at the accepted document version."
       );
@@ -5988,6 +6021,7 @@ var WSClient = class {
       reconnectScheduled: false
     };
     this.ws = null;
+    this.connectPromise = null;
     this.emit("close", info);
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
@@ -6025,13 +6059,89 @@ var WSClient = class {
       );
       return;
     }
+    if ("type" in message && message.type === "job_action_trace") {
+      const update = message;
+      if (typeof update.jobId !== "string" || update.jobId.length === 0 || !Number.isSafeInteger(update.documentEpoch) || update.documentEpoch < 0 || !Number.isSafeInteger(update.documentRevision) || update.documentRevision < 0 || !Array.isArray(update.actionTrace) || update.actionTrace.length > 128 || !update.actionTrace.every(
+        (event) => event && typeof event === "object" && typeof event.id === "string" && typeof event.timestamp === "number" && Number.isFinite(event.timestamp)
+      ) || !Array.isArray(update.actionSummary) || update.actionSummary.length > 16 || !update.actionSummary.every((line) => typeof line === "string") || typeof update.actionSummaryText !== "string" || update.actionSummaryText.length > 8e3) {
+        console.warn("[Granular] Ignoring invalid job_action_trace message");
+        return;
+      }
+      const currentVersion = documentVersion(this.doc);
+      if (update.documentEpoch < currentVersion.epoch || update.documentEpoch === currentVersion.epoch && update.documentRevision < currentVersion.revision) {
+        return;
+      }
+      if (update.documentEpoch > currentVersion.epoch || update.documentEpoch === currentVersion.epoch && update.documentRevision > currentVersion.revision) {
+        return;
+      }
+      const current = Automerge__namespace.toJS(this.doc);
+      const job = current.jobs?.byId?.[update.jobId];
+      if (job && typeof job === "object" && !Array.isArray(job)) {
+        job.actionTrace = update.actionTrace;
+        job.actionSummary = update.actionSummary;
+        job.actionSummaryText = update.actionSummaryText;
+        const lastEvent = update.actionTrace[update.actionTrace.length - 1];
+        if (lastEvent && typeof lastEvent.timestamp === "number") {
+          job.lastActionAt = lastEvent.timestamp;
+        }
+        this.doc = Automerge__namespace.from(current);
+        this.emit("job_action_trace", update);
+        this.emit("sync", this.doc);
+      }
+      return;
+    }
+    if ("type" in message && message.type === "feed_transient_patch") {
+      const update = message;
+      if (!Number.isSafeInteger(update.documentEpoch) || update.documentEpoch < 0 || !Number.isSafeInteger(update.documentRevision) || update.documentRevision < 0 || !Number.isSafeInteger(update.feedRevision) || update.feedRevision < 0 || !Number.isSafeInteger(update.lastTransientOrdinal) || update.lastTransientOrdinal < 0 || !Array.isArray(update.changes) || update.changes.length > 128 || !update.changes.every((change) => {
+        if (!change || typeof change !== "object" || typeof change.transientId !== "string" || change.transientId.length === 0) {
+          return false;
+        }
+        if (change.removed === true) return change.item === void 0;
+        const item = change.item;
+        return Boolean(
+          item && typeof item === "object" && !Array.isArray(item) && item.id === change.transientId
+        );
+      })) {
+        console.warn("[Granular] Ignoring invalid feed_transient_patch");
+        return;
+      }
+      const currentVersion = documentVersion(this.doc);
+      if (update.documentEpoch > currentVersion.epoch || update.documentEpoch === currentVersion.epoch && update.documentRevision > currentVersion.revision || update.documentEpoch < currentVersion.epoch || update.documentEpoch === currentVersion.epoch && update.documentRevision < currentVersion.revision) {
+        return;
+      }
+      const current = Automerge__namespace.toJS(this.doc);
+      const feed = current.feed;
+      if (!feed || typeof feed !== "object" || Array.isArray(feed)) return;
+      if (Number.isSafeInteger(feed.revision) && feed.revision > update.feedRevision) {
+        return;
+      }
+      if (Number.isSafeInteger(feed.lastTransientOrdinal) && feed.lastTransientOrdinal > update.lastTransientOrdinal) {
+        return;
+      }
+      if (!feed.transientById || typeof feed.transientById !== "object") {
+        feed.transientById = {};
+      }
+      for (const change of update.changes) {
+        if (change.removed === true) {
+          delete feed.transientById[change.transientId];
+        } else {
+          feed.transientById[change.transientId] = change.item;
+        }
+      }
+      feed.revision = update.feedRevision;
+      feed.lastTransientOrdinal = update.lastTransientOrdinal;
+      this.doc = Automerge__namespace.from(current);
+      this.emit("feed_transient_patch", update);
+      this.emit("sync", this.doc);
+      return;
+    }
     if ("type" in message && message.type === "snapshot_reset") {
       const resetMessage = message;
       try {
-        if (!Number.isSafeInteger(resetMessage.documentEpoch) || resetMessage.documentEpoch <= 0 || !Number.isSafeInteger(resetMessage.documentRevision) || resetMessage.documentRevision < 0 || !Array.isArray(resetMessage.data)) {
+        if (!Number.isSafeInteger(resetMessage.documentEpoch) || resetMessage.documentEpoch <= 0 || !Number.isSafeInteger(resetMessage.documentRevision) || resetMessage.documentRevision < 0 || !Array.isArray(resetMessage.data) && (!resetMessage.document || typeof resetMessage.document !== "object" || Array.isArray(resetMessage.document))) {
           throw new Error("snapshot_reset metadata is invalid");
         }
-        const replacement = Automerge__namespace.load(
+        const replacement = resetMessage.document ? Automerge__namespace.from(resetMessage.document) : Automerge__namespace.load(
           this.decodeDocumentBytes(
             resetMessage.data,
             "Automerge snapshot_reset"
@@ -6045,7 +6155,10 @@ var WSClient = class {
             "snapshot_reset metadata does not match the saved document"
           );
         }
-        if (!this.canAcceptDocumentReplacement(replacement, true)) {
+        const isJsonReplacement = Boolean(resetMessage.document);
+        if (!this.canAcceptDocumentReplacement(replacement, !isJsonReplacement, {
+          allowEqualRevisionPresentation: isJsonReplacement
+        })) {
           if (this.documentRepairRequired) {
             this.requireDocumentResync(
               "Stale Automerge snapshot_reset during document repair",
@@ -6338,30 +6451,30 @@ function parseJsonPromptChoiceOption(option) {
 }
 function normalizePromptChoiceOption(option) {
   if (typeof option === "string") {
-    const record2 = parseJsonPromptChoiceOption(option);
-    if (!record2) {
+    const record3 = parseJsonPromptChoiceOption(option);
+    if (!record3) {
       return { value: option, label: option };
     }
-    const value2 = typeof record2.value === "string" ? record2.value : typeof record2.id === "string" ? record2.id : typeof record2.label === "string" ? record2.label : JSON.stringify(record2);
+    const value2 = typeof record3.value === "string" ? record3.value : typeof record3.id === "string" ? record3.id : typeof record3.label === "string" ? record3.label : JSON.stringify(record3);
     return {
       value: value2,
-      label: typeof record2.label === "string" ? record2.label : value2,
-      description: typeof record2.description === "string" ? record2.description : void 0
+      label: typeof record3.label === "string" ? record3.label : value2,
+      description: typeof record3.description === "string" ? record3.description : void 0
     };
   }
-  const record = option;
-  if (!record) {
+  const record2 = option;
+  if (!record2) {
     return { value: "", label: "" };
   }
-  const nestedJson = (typeof record.value === "string" ? parseJsonPromptChoiceOption(record.value) : null) || (typeof record.label === "string" ? parseJsonPromptChoiceOption(record.label) : null);
+  const nestedJson = (typeof record2.value === "string" ? parseJsonPromptChoiceOption(record2.value) : null) || (typeof record2.label === "string" ? parseJsonPromptChoiceOption(record2.label) : null);
   if (nestedJson) {
     return normalizePromptChoiceOption(nestedJson);
   }
-  const value = typeof record.value === "string" ? record.value : typeof record.label === "string" ? record.label : JSON.stringify(record);
+  const value = typeof record2.value === "string" ? record2.value : typeof record2.label === "string" ? record2.label : JSON.stringify(record2);
   return {
     value,
-    label: typeof record.label === "string" ? record.label : value,
-    description: typeof record.description === "string" ? record.description : void 0
+    label: typeof record2.label === "string" ? record2.label : value,
+    description: typeof record2.description === "string" ? record2.description : void 0
   };
 }
 function scorePromptChoiceMatch(answer, answerTokens, option) {
@@ -6653,18 +6766,18 @@ var Session = class {
         get revision() {
           return current.revision;
         },
-        async update(text, options = {}) {
+        async update(text2, options = {}) {
           current = await track(
-            current.update(text, {
+            current.update(text2, {
               ...options,
               operationId: options.operationId || nextOperationId("transient-update")
             })
           );
           return wrapped;
         },
-        settle(text, options = {}) {
+        settle(text2, options = {}) {
           return track(
-            current.settle(text, {
+            current.settle(text2, {
               ...options,
               operationId: options.operationId || nextOperationId("transient-settle")
             })
@@ -6674,14 +6787,14 @@ var Session = class {
       return wrapped;
     };
     return {
-      feedback: (text, options = {}) => track(
-        publisher.feedback(text, {
+      feedback: (text2, options = {}) => track(
+        publisher.feedback(text2, {
           ...options,
           operationId: options.operationId || nextOperationId("feedback")
         })
       ),
-      transientFeedback: (text, options = {}) => track(
-        publisher.transientFeedback(text, {
+      transientFeedback: (text2, options = {}) => track(
+        publisher.transientFeedback(text2, {
           ...options,
           operationId: options.operationId || nextOperationId("transient-create")
         }).then(wrapTransientHandle)
@@ -7869,8 +7982,8 @@ function artifactRecordsById(liveDoc) {
   const byId = asRecord3(artifacts?.byId) || {};
   return Object.fromEntries(
     Object.entries(byId).map(([artifactId, value]) => {
-      const record = asRecord3(value);
-      return record ? [artifactId, record] : null;
+      const record2 = asRecord3(value);
+      return record2 ? [artifactId, record2] : null;
     }).filter((entry) => Boolean(entry))
   );
 }
@@ -7903,8 +8016,8 @@ function latestInputEditSummary(metadata) {
   ].filter(Boolean);
   return `lastEdit=${source}${actor ? ` by ${actor}` : ""}${changed.length ? ` (${changed.join("; ")})` : ""}`;
 }
-function artifactIssueSummary(record) {
-  const validation = asRecord3(record.validation);
+function artifactIssueSummary(record2) {
+  const validation = asRecord3(record2.validation);
   if (!validation) return null;
   const issues = Array.isArray(validation.issues) ? validation.issues.map((issue) => asRecord3(issue)).filter((issue) => Boolean(issue)).slice(0, 3) : [];
   if (issues.length > 0) {
@@ -7951,18 +8064,18 @@ function artifactStatePathSummary(metadata) {
   ].filter(Boolean);
   return pieces.length ? pieces.join("; ") : null;
 }
-function artifactSummaryLine(artifactId, record) {
-  if (!record) return `- ${artifactId}: unavailable in session artifact store`;
-  const label = trimString(record.label) || artifactId;
-  const kind = asString(record.kind) || "artifact";
-  const status = asString(record.status) || "unknown";
-  const createdByJobId = asString(record.createdByJobId);
-  const target = asRecord3(record.target);
-  const metadata = asRecord3(record.metadata) || {};
-  const subArtifactIds = Array.isArray(record.subArtifactIds) ? record.subArtifactIds.filter(
+function artifactSummaryLine(artifactId, record2) {
+  if (!record2) return `- ${artifactId}: unavailable in session artifact store`;
+  const label = trimString(record2.label) || artifactId;
+  const kind = asString(record2.kind) || "artifact";
+  const status = asString(record2.status) || "unknown";
+  const createdByJobId = asString(record2.createdByJobId);
+  const target = asRecord3(record2.target);
+  const metadata = asRecord3(record2.metadata) || {};
+  const subArtifactIds = Array.isArray(record2.subArtifactIds) ? record2.subArtifactIds.filter(
     (id) => typeof id === "string" && id.trim().length > 0
   ).slice(0, 8) : [];
-  const relationships = compactJson(record.relationships, 220);
+  const relationships = compactJson(record2.relationships, 220);
   const pieces = [
     `kind=${kind}`,
     `status=${status}`,
@@ -7970,7 +8083,7 @@ function artifactSummaryLine(artifactId, record) {
     target ? `target=${asString(target.className) || "record"}:${asString(target.id) || "unknown"}${asString(target.label) ? ` (${asString(target.label)})` : ""}` : null,
     artifactStatePathSummary(metadata),
     artifactExecutionSummary(metadata),
-    artifactIssueSummary(record),
+    artifactIssueSummary(record2),
     latestInputEditSummary(metadata),
     subArtifactIds.length ? `subArtifacts=${subArtifactIds.join(",")}` : null,
     relationships ? `relationships=${relationships}` : null
@@ -12390,6 +12503,7 @@ var StateMachineTransitionSchema = external_exports.object({
   to: external_exports.string().min(1),
   label: external_exports.string().optional(),
   description: external_exports.string().optional(),
+  userVisible: external_exports.boolean().optional(),
   action: StateTransitionActionSchema.optional(),
   assignee: StateTransitionAssigneeSchema.optional(),
   requirements: StateTransitionRequirementsSchema.optional(),
@@ -12474,6 +12588,7 @@ var CreatesSchema = external_exports.union([
     idPath: external_exports.string().min(1).optional(),
     pathPath: external_exports.string().min(1).optional(),
     statePath: external_exports.string().min(1).optional(),
+    completionState: external_exports.string().min(1).optional(),
     classStateHandle: external_exports.boolean().optional()
   }).strict()
 ]);
@@ -12823,6 +12938,7 @@ function normalizeCreationSummary(metamodels) {
     ...typeof raw.idPath === "string" && raw.idPath.trim() ? { idPath: raw.idPath.trim() } : {},
     ...typeof raw.pathPath === "string" && raw.pathPath.trim() ? { pathPath: raw.pathPath.trim() } : {},
     ...typeof raw.statePath === "string" && raw.statePath.trim() ? { statePath: raw.statePath.trim() } : {},
+    ...typeof raw.completionState === "string" && raw.completionState.trim() ? { completionState: raw.completionState.trim() } : {},
     ...typeof raw.classStateHandle === "boolean" ? { classStateHandle: raw.classStateHandle } : {}
   };
 }
@@ -12948,7 +13064,7 @@ var effectBehaviorsMetamodelPackage = defineMetamodelPackage({
       },
       {
         key: "creates",
-        description: 'Marks a static method as an allowed creator for a class. Use `creates: "class_name"` or `{ className, idPath, pathPath, statePath, classStateHandle }`.'
+        description: 'Marks a static method as an allowed creator for a class. Use `creates: "class_name"` or `{ className, idPath, pathPath, statePath, completionState, classStateHandle }`.'
       }
     ]
   },
@@ -13171,18 +13287,18 @@ function validateScalarRecord(value, path) {
 }
 function validateProjectedRecord(value, path) {
   validateObjectReference(value, path);
-  const record = value;
-  if (record.label !== void 0) {
-    if (typeof record.label !== "string") {
+  const record2 = value;
+  if (record2.label !== void 0) {
+    if (typeof record2.label !== "string") {
       throw new Error(`${path}.label must be a string`);
     }
-    if (record.label.length > MAX_SAFE_TEXT_LENGTH) {
+    if (record2.label.length > MAX_SAFE_TEXT_LENGTH) {
       throw new Error(
         `${path}.label exceeds ${MAX_SAFE_TEXT_LENGTH} characters`
       );
     }
   }
-  validateScalarRecord(record.fields, `${path}.fields`);
+  validateScalarRecord(record2.fields, `${path}.fields`);
 }
 function validateBoundedJson(value, path, depth = 0) {
   if (depth > 12) throw new Error(`${path} is nested too deeply`);
@@ -13232,6 +13348,11 @@ function validateProjectionResult(declaration, projection) {
       "projection.source.version"
     );
   }
+  if (projection.source.versionScope !== void 0 && projection.source.versionScope !== "global" && projection.source.versionScope !== "target") {
+    throw new Error(
+      "projection.source.versionScope must be 'global' or 'target'"
+    );
+  }
   if (!Array.isArray(projection.changes)) {
     throw new Error("projection.changes must be an array");
   }
@@ -13595,18 +13716,18 @@ function createInvocationFeedbackContext(bridge) {
       get revision() {
         return current.revision;
       },
-      async update(text, options = {}) {
+      async update(text2, options = {}) {
         current = await track(
-          current.update(text, {
+          current.update(text2, {
             ...options,
             operationId: options.operationId || nextOperationId("transient-update")
           })
         );
         return wrapped;
       },
-      settle(text, options = {}) {
+      settle(text2, options = {}) {
         return track(
-          current.settle(text, {
+          current.settle(text2, {
             ...options,
             operationId: options.operationId || nextOperationId("transient-settle")
           })
@@ -13616,17 +13737,17 @@ function createInvocationFeedbackContext(bridge) {
     return wrapped;
   };
   return {
-    feedback(text, options = {}) {
+    feedback(text2, options = {}) {
       return track(
-        publisher.feedback(text, {
+        publisher.feedback(text2, {
           ...options,
           operationId: options.operationId || nextOperationId("feedback")
         })
       );
     },
-    transientFeedback(text, options = {}) {
+    transientFeedback(text2, options = {}) {
       return track(
-        publisher.transientFeedback(text, {
+        publisher.transientFeedback(text2, {
           ...options,
           operationId: options.operationId || nextOperationId("transient-create")
         }).then(wrapTransientHandle)
@@ -14474,9 +14595,9 @@ var noteMetamodelPackage = defineMetamodelPackage({
           notes: async (ant) => await run(ant.notes())
         },
         ModelMutation: {
-          add_note: async (ant, { text }) => {
-            const model = await run(ant.add_note(text));
-            return { model, text };
+          add_note: async (ant, { text: text2 }) => {
+            const model = await run(ant.add_note(text2));
+            return { model, text: text2 };
           }
         }
       };
@@ -14889,6 +15010,7 @@ function normalizeStateMachines(values) {
       to: String(transition?.to?.name || ""),
       label: typeof transition?.label === "string" ? transition.label : null,
       description: typeof transition?.description === "string" ? transition.description : null,
+      userVisible: typeof transition?.user_visible === "boolean" ? transition.user_visible : typeof transition?.userVisible === "boolean" ? transition.userVisible : null,
       action: parseJsonRecord(transition?.action) || parseJsonRecord(transition?.action_json),
       assignee: parseJsonRecord(transition?.assignee) || parseJsonRecord(transition?.assignee_json),
       requirements: parseJsonRecord(transition?.requirements) || parseJsonRecord(transition?.requirements_json),
@@ -14960,6 +15082,9 @@ function transitionMetadataGraphqlArgs(transition) {
   if (typeof transition.description === "string") {
     args.push(`description: ${JSON.stringify(transition.description)}`);
   }
+  if (typeof transition.userVisible === "boolean") {
+    args.push(`user_visible: ${transition.userVisible}`);
+  }
   if (transition.action) {
     args.push(
       `action_json: ${JSON.stringify(JSON.stringify(transition.action))}`
@@ -15271,7 +15396,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
         name: String!
         state_machine: StateMachine!
         add_state(name: String!, is_final: Boolean, label: String, description: String): StateMachineMutation!
-        add_transition(name: String!, from: String!, to: String!, label: String, description: String, action_json: String, assignee_json: String, requirements_json: String, permission_json: String, risk: String, expected_outcome_json: String, outcomes_json: String): StateMachineMutation!
+        add_transition(name: String!, from: String!, to: String!, label: String, description: String, user_visible: Boolean, action_json: String, assignee_json: String, requirements_json: String, permission_json: String, risk: String, expected_outcome_json: String, outcomes_json: String): StateMachineMutation!
         activate_transition(name: String!): StateMachineMutation!
       }
 
@@ -15329,6 +15454,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
         to: StateMachineState!
         label: String
         description: String
+        user_visible: Boolean
         action_json: String
         assignee_json: String
         requirements_json: String
@@ -15410,6 +15536,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             to,
             label,
             description,
+            user_visible,
             action_json,
             assignee_json,
             requirements_json,
@@ -15427,6 +15554,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
                 {
                   label,
                   description,
+                  userVisible: user_visible,
                   actionJson: action_json,
                   assigneeJson: assignee_json,
                   requirementsJson: requirements_json,
@@ -15491,6 +15619,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
           to: (value) => value.to_state || { name: value.to, is_final: false },
           label: (value) => value.label || null,
           description: (value) => value.description || null,
+          user_visible: (value) => value.user_visible ?? null,
           action_json: (value) => value.action_json || null,
           assignee_json: (value) => value.assignee_json || null,
           requirements_json: (value) => value.requirements_json || null,
@@ -15577,6 +15706,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             to { name }
             label
             description
+            user_visible
             action_json
             assignee_json
             requirements_json
@@ -15984,6 +16114,786 @@ function buildEffectMetamodelMutations(toolPath, spec) {
   );
 }
 
+// src/artifact-workflow.ts
+var TERMINAL_ARTIFACT_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "partially_completed",
+  "failed",
+  "canceled"
+]);
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function text(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function humanize(value) {
+  const words = value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim();
+  return words ? words[0].toUpperCase() + words.slice(1) : "Details";
+}
+function stableToken(value) {
+  return encodeURIComponent(value.trim().toLowerCase());
+}
+function isMissing(value) {
+  return value === null || value === void 0 || typeof value === "string" && !value.trim() || Array.isArray(value) && value.length === 0;
+}
+function displayValue(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(displayValue).filter(Boolean).join(", ");
+  }
+  return "Provided";
+}
+function artifactFields(artifact) {
+  return Array.isArray(artifact.inputSchema?.fields) ? artifact.inputSchema.fields.filter(
+    (field) => Boolean(record(field))
+  ) : [];
+}
+function declaredSections(artifact) {
+  const fields = artifactFields(artifact);
+  if (!fields.length) return [];
+  const knownNames = new Set(
+    fields.map((field) => text(field.name)).filter((name) => Boolean(name))
+  );
+  const ui = record(artifact.inputSchema?.ui);
+  const workflow = record(ui?.workflow);
+  const rawSections = Array.isArray(workflow?.steps) ? workflow.steps : Array.isArray(ui?.sections) ? ui.sections : [];
+  const used = /* @__PURE__ */ new Set();
+  const sections = rawSections.flatMap((value) => {
+    const section = record(value);
+    const id = text(section?.id);
+    const label = text(section?.label);
+    const fieldNames = Array.isArray(section?.fieldNames) ? section.fieldNames.map(text).filter(
+      (name) => name !== null && knownNames.has(name) && !used.has(name)
+    ) : [];
+    if (!id || !label || !fieldNames.length) return [];
+    fieldNames.forEach((name) => used.add(name));
+    return [{ id, label, description: text(section?.description), fieldNames }];
+  });
+  const remaining = [...knownNames].filter((name) => !used.has(name));
+  const chunkSize = 5;
+  const chunkCount = Math.ceil(remaining.length / chunkSize);
+  const hasDeclaredSections = sections.length > 0;
+  for (let index = 0; index < chunkCount; index += 1) {
+    const baseLabel = hasDeclaredSections ? "Other details" : "Details";
+    sections.push({
+      id: chunkCount === 1 ? hasDeclaredSections ? "other-details" : "details" : `${hasDeclaredSections ? "other-details" : "details"}-${index + 1}`,
+      label: chunkCount === 1 ? baseLabel : `${baseLabel} ${index + 1}`,
+      description: null,
+      fieldNames: remaining.slice(index * chunkSize, (index + 1) * chunkSize)
+    });
+  }
+  return sections;
+}
+function fieldValue(artifact, fieldName) {
+  const field = artifactFields(artifact).find(
+    (candidate) => text(candidate.name) === fieldName
+  );
+  const kind = text(field?.kind);
+  return kind === "relationshipOne" || kind === "relationshipMany" ? artifact.relationships?.[fieldName] : artifact.inputValues?.[fieldName];
+}
+function conditionallyRequired(artifact, field) {
+  const raw = field.requiredWhen ?? field.required_when;
+  const conditions = Array.isArray(raw) ? raw : raw ? [raw] : [];
+  return conditions.length > 0 && conditions.every((value) => {
+    const condition = record(value);
+    const dependency = text(condition?.field);
+    return Boolean(dependency) && Object.prototype.hasOwnProperty.call(condition || {}, "equals") && Object.is(fieldValue(artifact, dependency), condition.equals);
+  });
+}
+function fieldValidationRules(field) {
+  const raw = Array.isArray(field.validationRules) ? field.validationRules : Array.isArray(field.validation_rules) ? field.validation_rules : Array.isArray(field.validate) ? field.validate : [];
+  return raw.filter(
+    (rule) => Boolean(record(rule)) && typeof record(rule)?.operator === "string"
+  );
+}
+function fieldProvenanceNeedsReview(artifact, field) {
+  const fieldName = text(field.name);
+  if (!fieldName) return false;
+  const namespace = text(field.kind)?.startsWith("relationship") ? "relationships" : "inputValues";
+  const provenance = artifact.fieldProvenance?.[`${namespace}.${fieldName}`];
+  if (!provenance) return false;
+  const confirmedAt = typeof provenance.confirmedAt === "number" ? provenance.confirmedAt : null;
+  const updatedAt = typeof provenance.updatedAt === "number" ? provenance.updatedAt : null;
+  const invalidatedAt = typeof provenance.invalidatedAt === "number" ? provenance.invalidatedAt : null;
+  const explicitlyConfirmed = confirmedAt !== null && (updatedAt === null || confirmedAt >= updatedAt) && (invalidatedAt === null || confirmedAt >= invalidatedAt);
+  if (explicitlyConfirmed) return false;
+  const invalidated = invalidatedAt !== null && (confirmedAt === null || confirmedAt < invalidatedAt);
+  const assistantSource = [
+    "user_statement",
+    "agent_extraction",
+    "agent_inference",
+    "provider_lookup",
+    "ontology_default"
+  ].includes(provenance.source);
+  return invalidated || assistantSource && provenance.confidence === "ambiguous";
+}
+function sectionComplete(artifact, fieldNames) {
+  const schema = record(artifact.inputSchema);
+  const declaredRequiredNames = new Set(
+    [
+      ...Array.isArray(schema?.required) ? schema.required : [],
+      ...Array.isArray(schema?.["x-granular-artifact-required"]) ? schema["x-granular-artifact-required"] : []
+    ].map(text).filter((name) => Boolean(name))
+  );
+  const validation = record(artifact.validation);
+  const invalidFieldNames = new Set(
+    (Array.isArray(validation?.issues) ? validation.issues : []).map(record).filter((issue) => Boolean(issue)).map((issue) => text(issue.path) || text(issue.field)).filter((path) => Boolean(path)).map((path) => path.replace(/^(inputValues|relationships)\./, ""))
+  );
+  const fieldsByName = new Map(
+    artifactFields(artifact).map((field) => [text(field.name), field])
+  );
+  return fieldNames.every((fieldName) => {
+    if (invalidFieldNames.has(fieldName)) return false;
+    const field = fieldsByName.get(fieldName);
+    if (!field) return true;
+    if (fieldProvenanceNeedsReview(artifact, field)) return false;
+    const required = declaredRequiredNames.has(fieldName) || field.required === true || conditionallyRequired(artifact, field);
+    const value = fieldValue(artifact, fieldName);
+    const provenance = artifact.fieldProvenance?.[`${text(field.kind)?.startsWith("relationship") ? "relationships" : "inputValues"}.${fieldName}`];
+    if (provenance?.invalidatedAt) return false;
+    if (text(field.kind)?.startsWith("relationship")) {
+      const resolvers = record(
+        record(artifact.metadata)?.relationshipResolvers
+      );
+      const resolverStatus = text(record(resolvers?.[fieldName])?.status);
+      if (resolverStatus === "missing") return false;
+      if (resolverStatus === "choice" && isMissing(value)) return false;
+    }
+    if (required && isMissing(value)) return false;
+    if (isMissing(value)) return true;
+    return fieldValidationRules(field).every(
+      (rule) => evaluateValidationRule(value, rule).passed
+    );
+  });
+}
+function sectionRecap(artifact, fieldNames) {
+  const fields = artifactFields(artifact);
+  const fieldsByName = new Map(
+    fields.map((field) => [text(field.name), field])
+  );
+  const labels = new Map(
+    fields.map((field) => [
+      text(field.name),
+      text(field.label) || humanize(text(field.name) || "detail")
+    ])
+  );
+  const items = fieldNames.flatMap((fieldName) => {
+    const value = fieldValue(artifact, fieldName);
+    if (isMissing(value)) return [];
+    const field = fieldsByName.get(fieldName);
+    const relationshipLabels = record(
+      record(artifact.metadata)?.relationshipLabels
+    );
+    const fieldLabels = record(relationshipLabels?.[fieldName]);
+    const resolvers = record(record(artifact.metadata)?.relationshipResolvers);
+    const candidates = Array.isArray(record(resolvers?.[fieldName])?.candidates) ? record(resolvers?.[fieldName])?.candidates : [];
+    const candidateLabel = candidates.map(record).find((candidate) => text(candidate?.id) === value)?.label;
+    const rawOptions = Array.isArray(field?.enumOptions) ? field.enumOptions : Array.isArray(field?.options) ? field.options : [];
+    const enumLabel = rawOptions.map(
+      (option) => typeof option === "string" ? { value: option, label: humanize(option) } : record(option)
+    ).find((option) => text(option?.value) === value)?.label;
+    const rendered = typeof value === "string" && text(fieldLabels?.[value]) ? text(fieldLabels?.[value]) : typeof value === "string" && text(candidateLabel) ? text(candidateLabel) : typeof value === "string" && text(enumLabel) ? text(enumLabel) : typeof value === "string" && (text(field?.kind) === "enum" || text(field?.kind)?.startsWith("relationship")) ? humanize(value) : displayValue(value);
+    return [
+      { label: labels.get(fieldName) || humanize(fieldName), value: rendered }
+    ];
+  });
+  return {
+    summary: items.length ? items.map((item) => `${item.label}: ${item.value}`).join(" \xB7 ") : "Completed",
+    items
+  };
+}
+function operationPhase(artifact) {
+  const execution = record(record(artifact.metadata)?.execution);
+  const phase = text(execution?.phase);
+  if (artifact.status === "completed") return "completed";
+  if (artifact.status === "failed") return "failed";
+  if (artifact.status === "awaiting_human") return "waiting_for_approval";
+  if (phase === "preparing") return "reviewing";
+  if (phase === "syncing_record") return "synchronizing";
+  if (phase === "verifying_target") return "verifying";
+  if (artifact.status === "running") return "sending";
+  return null;
+}
+function operationLabel(artifact) {
+  const ui = record(artifact.inputSchema?.ui);
+  const workflow = record(ui?.workflow);
+  const effect = record(record(artifact.metadata)?.effect);
+  return text(workflow?.operationLabel) || text(ui?.submitLabel) || text(effect?.activityLabel) || text(effect?.label) || artifact.label;
+}
+function relationshipValueContainsRecordId(value, recordId) {
+  return Array.isArray(value) ? value.some((item) => item === recordId) : value === recordId;
+}
+function relationshipChildLinkPending(parent, fieldName, child) {
+  if (child.status !== "completed") return false;
+  const parentMetadata = record(parent.metadata);
+  const linkMarker = record(
+    record(parentMetadata?.relationshipLinkProvenance)?.[fieldName]
+  );
+  const relationshipValue = parent.relationships?.[fieldName];
+  const childExecution = record(record(child.metadata)?.execution);
+  const childResult = record(childExecution?.result);
+  const childCommit = record(childResult?.commit);
+  const primaryTarget2 = record(childCommit?.primaryTarget);
+  const committedRecordId = text(primaryTarget2?.id);
+  const markerRecordId = text(linkMarker?.recordId);
+  const exactRecordId = markerRecordId || committedRecordId;
+  if (exactRecordId) {
+    return !relationshipValueContainsRecordId(relationshipValue, exactRecordId);
+  }
+  return isMissing(relationshipValue);
+}
+function stateTransitionSteps(artifact) {
+  if (artifact.kind !== "state_path") return [];
+  const statePlan = record(record(artifact.metadata)?.statePlan);
+  const plan = record(statePlan?.plan);
+  const transitionMetadata = record(statePlan?.transitionMetadata);
+  const rawSteps = Array.isArray(statePlan?.steps) ? statePlan.steps : Array.isArray(plan?.steps) ? plan.steps : [];
+  return Array.from(rawSteps).flatMap((value, fallbackIndex) => {
+    const step = record(value);
+    const transition = text(step?.transition);
+    if (!step || !transition) return [];
+    const transitionDescription = record(transitionMetadata?.[transition]);
+    const userVisible = typeof step.userVisible === "boolean" ? step.userVisible : typeof transitionDescription?.userVisible === "boolean" ? transitionDescription.userVisible : true;
+    const blockers = Array.isArray(step.blockers) ? step.blockers.filter(
+      (blocker) => Boolean(record(blocker))
+    ) : [];
+    return [
+      {
+        index: typeof step.index === "number" ? step.index : fallbackIndex,
+        transition,
+        label: text(step.label) || humanize(transition),
+        description: text(step.description) || text(record(step.expectedOutcome)?.summary) || null,
+        status: text(step.status) || "pending",
+        // State plans may contain bookkeeping transitions that are necessary
+        // for execution/audit but are already represented by an actionable
+        // form or by the single final operation. Producers must opt those
+        // transitions out explicitly; the client never infers this from a
+        // label or transition name.
+        userVisible,
+        blockers
+      }
+    ];
+  });
+}
+function stateTransitionGroupLabel(artifact) {
+  if (artifact.kind !== "state_path") return null;
+  const statePlan = record(record(artifact.metadata)?.statePlan);
+  const classLabel = text(statePlan?.classLabel);
+  return classLabel ? `${classLabel} workflow` : null;
+}
+function workflowGroupStatus(nodes) {
+  const active = nodes.find(
+    (node) => ["current", "needs_input", "working", "blocked", "failed"].includes(
+      node.status
+    )
+  );
+  if (active) return active.status;
+  if (nodes.some((node) => node.status === "upcoming")) return "upcoming";
+  const lastTerminal = [...nodes].reverse().find((node) => isTerminalWorkflowStepStatus(node.status));
+  return lastTerminal?.status || nodes[0]?.status || "upcoming";
+}
+function transitionNodeStatus(artifact, step) {
+  const statePlan = record(record(artifact.metadata)?.statePlan);
+  const currentStep = record(statePlan?.currentStep);
+  const execution = record(record(artifact.metadata)?.execution);
+  const currentTransition = text(execution?.currentTransition);
+  const completedTransitions = new Set(
+    Array.isArray(execution?.completedTransitions) ? execution.completedTransitions.map(text).filter((value) => Boolean(value)) : []
+  );
+  const isCurrent = currentTransition === step.transition || currentStep?.index === step.index;
+  if (completedTransitions.has(step.transition) || step.status === "completed") {
+    return "completed";
+  }
+  if (isCurrent && artifact.status === "failed") return "failed";
+  if (isCurrent && artifact.status === "canceled") return "canceled";
+  if (isCurrent && artifact.status === "running") return "working";
+  if (step.status === "failed") return "failed";
+  if (artifact.status === "canceled") return "canceled";
+  if (step.status === "blocked") return "blocked";
+  if (step.status === "needs_other_user" || step.status === "needs_input") {
+    return "needs_input";
+  }
+  if (isCurrent || step.status === "ready" || step.status === "current") {
+    return "current";
+  }
+  if (step.status === "skipped") return "skipped";
+  if (step.status === "canceled") return "canceled";
+  return "upcoming";
+}
+var TERMINAL_WORKFLOW_STEP_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "skipped",
+  "canceled"
+]);
+function isArtifactWorkflowNodeTerminal(nodeOrStatus) {
+  const status = typeof nodeOrStatus === "string" ? nodeOrStatus : nodeOrStatus.status;
+  return TERMINAL_WORKFLOW_STEP_STATUSES.has(status);
+}
+function isTerminalWorkflowStepStatus(status) {
+  return isArtifactWorkflowNodeTerminal(status);
+}
+function firstTransitionStatus(artifact, status) {
+  if (status !== "upcoming") return status;
+  if (artifact.status === "canceled") return "canceled";
+  if (artifact.status === "failed") return "failed";
+  if (artifact.status === "blocked" || artifact.status === "stale" || artifact.status === "partially_completed") {
+    return "blocked";
+  }
+  if (artifact.status === "running") return "working";
+  if (artifact.status === "awaiting_human") return "needs_input";
+  return "current";
+}
+function operationStatus(artifact, transitionStatuses = []) {
+  if (artifact.status === "completed") {
+    if (transitionStatuses.some(
+      (status) => !TERMINAL_WORKFLOW_STEP_STATUSES.has(status)
+    )) {
+      if (transitionStatuses.includes("failed")) return "failed";
+      if (transitionStatuses.includes("needs_input")) return "needs_input";
+      if (transitionStatuses.includes("working")) return "working";
+      if (transitionStatuses.includes("current")) return "current";
+      return "blocked";
+    }
+    return "completed";
+  }
+  if (artifact.status === "failed") return "failed";
+  if (artifact.status === "canceled") return "canceled";
+  if (artifact.status === "partially_completed") return "blocked";
+  if (artifact.status === "blocked" || artifact.status === "stale")
+    return "blocked";
+  if (artifact.status === "running") return "working";
+  if (artifact.status === "awaiting_human") return "needs_input";
+  if (artifact.status === "ready") return "current";
+  return "upcoming";
+}
+function semanticWorkflow(workflow) {
+  const { revision: _revision, updatedAt: _updatedAt, ...semantic } = workflow;
+  return semantic;
+}
+function isNavigationOnlyOperation(workflow, node) {
+  const hasExplicitTransitionLeaf = getArtifactWorkflowNodes(workflow).some(
+    (candidate) => candidate.childIds.length === 0 && candidate.kind === "transition"
+  );
+  return hasExplicitTransitionLeaf && node.childIds.length === 0 && node.kind === "operation" && // A terminal operation is redundant once authored state-path leaves are
+  // available. While it is still delivering/synchronizing, however, it is
+  // the only honest representation of the work still in progress.
+  isArtifactWorkflowNodeTerminal(node);
+}
+function getArtifactWorkflowNavigationLeaves(workflow) {
+  return getArtifactWorkflowNodes(workflow).filter(
+    (node) => isArtifactWorkflowNodeNavigableLeaf(workflow, node)
+  );
+}
+function isArtifactWorkflowNodeNavigableLeaf(workflow, node) {
+  return node.childIds.length === 0 && !isNavigationOnlyOperation(workflow, node);
+}
+function isArtifactWorkflowNodeActionable(node) {
+  return node.availability === "available" && ["current", "needs_input", "working", "blocked", "failed"].includes(
+    node.status
+  );
+}
+function getArtifactWorkflowNavigationTarget(workflow) {
+  const leaves = getArtifactWorkflowNavigationLeaves(workflow);
+  return leaves.find(
+    (node) => !isArtifactWorkflowNodeTerminal(node) && isArtifactWorkflowNodeActionable(node)
+  ) || leaves.at(-1) || null;
+}
+function projectArtifactWorkflow(artifact, allArtifacts = [artifact], now = artifact.updatedAt) {
+  const nodesById = {};
+  const rootNodeIds = [];
+  const sections = declaredSections(artifact);
+  const children = new Map(
+    allArtifacts.filter((candidate2) => candidate2.parentArtifactId === artifact.artifactId).map((candidate2) => [candidate2.artifactId, candidate2])
+  );
+  const relationshipChildren = record(
+    record(artifact.metadata)?.relationshipChildren
+  );
+  const operationId2 = `${artifact.artifactId}:operation`;
+  const validationId = `${artifact.artifactId}:validation`;
+  const sectionNodeIds = [];
+  let currentNodeId = null;
+  let foundIncompleteSection = false;
+  let foundActiveLeaf = false;
+  let transitionHasActiveStep = false;
+  let hasVisibleTransition = false;
+  const projectedTransitionStatuses = [];
+  const transitionNodeIds = [];
+  const transitionGroupLabel = stateTransitionGroupLabel(artifact);
+  const transitionGroupId = `${artifact.artifactId}:transition-group`;
+  for (const section of sections) {
+    const id = `${artifact.artifactId}:section:${stableToken(section.id)}`;
+    const complete = sectionComplete(artifact, section.fieldNames);
+    const blockedByEarlierSection = foundIncompleteSection;
+    const blockedByEarlierAction = foundIncompleteSection || foundActiveLeaf;
+    const relationshipFields = artifactFields(artifact).filter(
+      (field) => section.fieldNames.includes(text(field.name) || "") && ["relationshipOne", "relationshipMany"].includes(
+        text(field.kind) || ""
+      )
+    );
+    const relationshipField = relationshipFields[0];
+    const relationshipChildrenInSection = relationshipFields.flatMap(
+      (field) => {
+        const relationshipName = text(field.name);
+        const childArtifactId = relationshipName ? text(relationshipChildren?.[relationshipName]) : null;
+        const child = childArtifactId ? children.get(childArtifactId) : null;
+        if (!relationshipName || !child) return [];
+        return [
+          {
+            relationshipName,
+            child,
+            childLinkPending: relationshipChildLinkPending(
+              artifact,
+              relationshipName,
+              child
+            ),
+            childId: `${artifact.artifactId}:child:${stableToken(child.artifactId)}`
+          }
+        ];
+      }
+    );
+    const relationshipChildFieldNames = new Set(
+      relationshipChildrenInSection.map(
+        ({ relationshipName }) => relationshipName
+      )
+    );
+    const residualFieldNames = section.fieldNames.filter(
+      (fieldName) => !relationshipChildFieldNames.has(fieldName)
+    );
+    const residualComplete = sectionComplete(artifact, residualFieldNames);
+    const residualId = `${id}:details`;
+    const childActive = relationshipChildrenInSection.some(
+      ({ child, childLinkPending }) => childLinkPending || !TERMINAL_ARTIFACT_STATUSES.has(child.status)
+    );
+    const childIsWorking = relationshipChildrenInSection.some(
+      ({ child, childLinkPending }) => childLinkPending || child.status === "running"
+    );
+    const sectionStatus = complete && !blockedByEarlierSection ? "completed" : blockedByEarlierAction ? "upcoming" : childActive ? childIsWorking ? "working" : "needs_input" : !TERMINAL_ARTIFACT_STATUSES.has(artifact.status) ? "needs_input" : "upcoming";
+    if (!complete) foundIncompleteSection = true;
+    nodesById[id] = {
+      id,
+      artifactId: artifact.artifactId,
+      parentId: operationId2,
+      childIds: [
+        ...relationshipChildrenInSection.map(({ childId }) => childId),
+        ...relationshipChildrenInSection.length > 0 && residualFieldNames.length > 0 && !residualComplete ? [residualId] : []
+      ],
+      kind: relationshipChildrenInSection.length > 0 ? "group" : relationshipField ? "relationship" : "input",
+      label: section.label,
+      description: section.description,
+      status: sectionStatus,
+      availability: sectionStatus === "completed" ? "readonly" : sectionStatus === "upcoming" ? "unavailable" : "available",
+      fieldNames: relationshipChildrenInSection.length > 0 ? void 0 : section.fieldNames,
+      recap: sectionStatus === "completed" ? sectionRecap(artifact, section.fieldNames) : null,
+      completedAt: sectionStatus === "completed" ? artifact.updatedAt : null
+    };
+    sectionNodeIds.push(id);
+    const childStatuses = [];
+    for (const {
+      child,
+      childId,
+      childLinkPending
+    } of relationshipChildrenInSection) {
+      const authoritativeChildStatus = childLinkPending ? "working" : child.status === "completed" ? "completed" : child.status === "failed" ? "failed" : child.status === "canceled" ? "canceled" : child.status === "running" ? "working" : child.status === "blocked" || child.status === "stale" ? "blocked" : child.status === "ready" ? "current" : "needs_input";
+      const childStatus = blockedByEarlierSection ? "upcoming" : foundActiveLeaf && !isTerminalWorkflowStepStatus(authoritativeChildStatus) ? "upcoming" : authoritativeChildStatus;
+      childStatuses.push(childStatus);
+      nodesById[childId] = {
+        id: childId,
+        artifactId: artifact.artifactId,
+        parentId: id,
+        childIds: [],
+        kind: "child_artifact",
+        label: child.label,
+        description: child.description,
+        status: childStatus,
+        availability: childStatus === "completed" ? "readonly" : childStatus === "upcoming" ? "unavailable" : "available",
+        childArtifactId: child.artifactId,
+        recap: childStatus === "completed" ? { summary: `${child.label} completed`, items: [] } : null,
+        attention: childStatus === "failed" ? { title: `${child.label} failed`, retryable: true } : null,
+        startedAt: child.executedAt || null,
+        completedAt: childLinkPending ? null : child.completedAt || null
+      };
+      if (!blockedByEarlierSection && !isArtifactWorkflowNodeTerminal(childStatus)) {
+        if (!foundActiveLeaf) {
+          currentNodeId = childId;
+          foundActiveLeaf = true;
+        }
+      }
+    }
+    if (relationshipChildrenInSection.length > 0 && residualFieldNames.length > 0 && !residualComplete) {
+      const residualStatus = residualComplete ? "completed" : blockedByEarlierSection || foundActiveLeaf ? "upcoming" : !TERMINAL_ARTIFACT_STATUSES.has(artifact.status) ? "needs_input" : "upcoming";
+      const residualFields = artifactFields(artifact).filter(
+        (field) => residualFieldNames.includes(text(field.name) || "")
+      );
+      const residualLabel = residualFields.length === 1 ? text(residualFields[0]?.label) || section.label : "Details";
+      childStatuses.push(residualStatus);
+      nodesById[residualId] = {
+        id: residualId,
+        artifactId: artifact.artifactId,
+        parentId: id,
+        childIds: [],
+        kind: residualFields.some(
+          (field) => ["relationshipOne", "relationshipMany"].includes(
+            text(field.kind) || ""
+          )
+        ) ? "relationship" : "input",
+        label: residualLabel,
+        description: section.description,
+        status: residualStatus,
+        availability: residualStatus === "completed" ? "readonly" : residualStatus === "upcoming" ? "unavailable" : "available",
+        fieldNames: residualFieldNames,
+        recap: residualComplete ? sectionRecap(artifact, residualFieldNames) : null,
+        completedAt: residualComplete ? artifact.updatedAt : null
+      };
+      if (!foundActiveLeaf && ["needs_input", "working", "blocked", "failed"].includes(residualStatus)) {
+        currentNodeId = residualId;
+        foundActiveLeaf = true;
+      }
+    }
+    if (childStatuses.length > 0) {
+      const representativeChildStatus = childStatuses.find(
+        (status) => !isArtifactWorkflowNodeTerminal(status)
+      ) ?? (complete ? childStatuses.at(-1) : null);
+      if (representativeChildStatus) {
+        nodesById[id].status = representativeChildStatus;
+      }
+      nodesById[id].availability = "readonly";
+    }
+    if (!foundActiveLeaf && relationshipChildrenInSection.length === 0 && ["needs_input", "working", "blocked", "failed"].includes(sectionStatus)) {
+      currentNodeId = id;
+      foundActiveLeaf = true;
+    }
+  }
+  const transitionsAreGatedByForm = (foundIncompleteSection || foundActiveLeaf) && !TERMINAL_ARTIFACT_STATUSES.has(artifact.status);
+  for (const step of stateTransitionSteps(artifact)) {
+    if (!step.userVisible) continue;
+    hasVisibleTransition = true;
+    const id = `${artifact.artifactId}:transition:${stableToken(step.transition)}`;
+    const rawStatus = transitionNodeStatus(artifact, step);
+    const status = isTerminalWorkflowStepStatus(rawStatus) ? rawStatus : transitionsAreGatedByForm || transitionHasActiveStep ? "upcoming" : firstTransitionStatus(artifact, rawStatus);
+    projectedTransitionStatuses.push(status);
+    if (!isTerminalWorkflowStepStatus(status)) {
+      transitionHasActiveStep = true;
+    }
+    const blocker = step.blockers[0];
+    nodesById[id] = {
+      id,
+      artifactId: artifact.artifactId,
+      parentId: transitionGroupLabel ? transitionGroupId : operationId2,
+      childIds: [],
+      kind: "transition",
+      label: step.label,
+      description: step.description,
+      status,
+      availability: status === "completed" ? "readonly" : status === "upcoming" ? "unavailable" : "available",
+      operationPhase: step.status === "needs_other_user" ? "waiting_for_approval" : status === "working" ? operationPhase(artifact) : null,
+      operationDetail: text(record(record(artifact.metadata)?.execution)?.message) || null,
+      recap: status === "completed" ? { summary: `${step.label} completed`, items: [] } : null,
+      attention: status === "failed" || status === "blocked" ? {
+        title: text(blocker?.label) || `${step.label} needs attention`,
+        detail: text(blocker?.detail) || text(blocker?.description) || null,
+        retryable: status === "failed"
+      } : null,
+      startedAt: status === "working" ? artifact.executedAt || artifact.updatedAt : null,
+      completedAt: status === "completed" ? artifact.updatedAt : null
+    };
+    transitionNodeIds.push(id);
+    if (!currentNodeId && !["completed", "upcoming", "skipped", "canceled"].includes(status)) {
+      currentNodeId = id;
+    }
+  }
+  if (transitionNodeIds.length) {
+    const transitionNodes = transitionNodeIds.map((id) => nodesById[id]).filter((node) => Boolean(node));
+    if (transitionGroupLabel) {
+      const groupStatus = workflowGroupStatus(transitionNodes);
+      const activeTransition = transitionNodes.find(
+        (node) => ["current", "needs_input", "working", "blocked", "failed"].includes(
+          node.status
+        )
+      );
+      nodesById[transitionGroupId] = {
+        id: transitionGroupId,
+        artifactId: artifact.artifactId,
+        parentId: operationId2,
+        childIds: transitionNodeIds,
+        kind: "group",
+        label: transitionGroupLabel,
+        description: null,
+        status: groupStatus,
+        availability: groupStatus === "upcoming" ? "unavailable" : groupStatus === "completed" ? "readonly" : "available",
+        operationPhase: activeTransition?.operationPhase || null,
+        startedAt: activeTransition?.startedAt || null,
+        completedAt: groupStatus === "completed" ? transitionNodes.at(-1)?.completedAt || artifact.updatedAt : null
+      };
+      sectionNodeIds.push(transitionGroupId);
+    } else {
+      sectionNodeIds.push(...transitionNodeIds);
+    }
+  }
+  const projectedOperationStatus = operationStatus(
+    artifact,
+    projectedTransitionStatuses
+  );
+  if (projectedOperationStatus === "completed") {
+    for (const transitionNodeId of transitionNodeIds) {
+      const transition = nodesById[transitionNodeId];
+      if (transition?.kind === "transition" && transition.status === "completed") {
+        transition.completionState = "graph_propagated";
+      }
+    }
+  }
+  const phase = operationPhase(artifact);
+  const activeDescendantStatus = currentNodeId ? nodesById[currentNodeId]?.status : null;
+  const finalStatus = activeDescendantStatus && !isTerminalWorkflowStepStatus(activeDescendantStatus) ? activeDescendantStatus : projectedOperationStatus;
+  const validationStatus = currentNodeId ? "upcoming" : projectedOperationStatus === "upcoming" ? "current" : projectedOperationStatus;
+  nodesById[validationId] = {
+    id: validationId,
+    artifactId: artifact.artifactId,
+    parentId: operationId2,
+    childIds: [],
+    kind: "operation",
+    label: operationLabel(artifact),
+    description: artifact.description || null,
+    status: validationStatus,
+    availability: validationStatus === "upcoming" ? "unavailable" : validationStatus === "completed" ? "readonly" : "available",
+    operationPhase: phase,
+    completionState: projectedOperationStatus === "completed" ? "graph_propagated" : phase === "synchronizing" || phase === "verifying" ? "effect_applied" : null,
+    operationDetail: text(
+      record(record(artifact.metadata)?.execution)?.message
+    ),
+    recap: validationStatus === "completed" ? { summary: `${artifact.label} completed`, items: [] } : null,
+    attention: validationStatus === "failed" ? { title: `${artifact.label} failed`, retryable: true } : validationStatus === "blocked" ? {
+      title: `${artifact.label} needs attention`,
+      retryable: artifact.status === "stale"
+    } : null,
+    startedAt: artifact.executedAt || null,
+    completedAt: artifact.completedAt || null
+  };
+  sectionNodeIds.push(validationId);
+  if (!currentNodeId && !hasVisibleTransition && !["completed", "canceled"].includes(finalStatus)) {
+    currentNodeId = validationId;
+  }
+  const rootStatus = currentNodeId === validationId ? nodesById[validationId].status : finalStatus;
+  nodesById[operationId2] = {
+    id: operationId2,
+    artifactId: artifact.artifactId,
+    parentId: null,
+    childIds: sectionNodeIds,
+    kind: "group",
+    label: artifact.label,
+    description: artifact.description || null,
+    status: rootStatus,
+    availability: rootStatus === "upcoming" ? "unavailable" : rootStatus === "completed" ? "readonly" : "available",
+    operationPhase: null,
+    startedAt: artifact.executedAt || null,
+    completedAt: artifact.completedAt || null
+  };
+  rootNodeIds.push(operationId2);
+  const candidateBeforeTarget = {
+    schemaVersion: 1,
+    revision: artifact.workflow?.revision || 1,
+    artifactId: artifact.artifactId,
+    rootNodeIds,
+    nodesById,
+    currentNodeId: null,
+    updatedAt: now
+  };
+  currentNodeId = getArtifactWorkflowNavigationTarget(candidateBeforeTarget)?.id || null;
+  const automaticTarget = currentNodeId ? nodesById[currentNodeId] || null : null;
+  const canonicalRootStatus = automaticTarget && !isArtifactWorkflowNodeTerminal(automaticTarget) ? automaticTarget.status : projectedOperationStatus;
+  nodesById[operationId2].status = canonicalRootStatus;
+  nodesById[operationId2].availability = canonicalRootStatus === "upcoming" ? "unavailable" : canonicalRootStatus === "completed" ? "readonly" : "available";
+  const candidate = {
+    ...candidateBeforeTarget,
+    currentNodeId
+  };
+  if (artifact.workflow && JSON.stringify(semanticWorkflow(artifact.workflow)) !== JSON.stringify(semanticWorkflow(candidate))) {
+    candidate.revision = artifact.workflow.revision + 1;
+  } else if (artifact.workflow) {
+    candidate.updatedAt = artifact.workflow.updatedAt;
+  }
+  return candidate;
+}
+function getCurrentArtifactWorkflowNode(workflow) {
+  return workflow.currentNodeId ? workflow.nodesById[workflow.currentNodeId] || null : null;
+}
+function getArtifactWorkflowNodes(workflow) {
+  const visit = (id) => {
+    const node = workflow.nodesById[id];
+    return node ? [node, ...node.childIds.flatMap(visit)] : [];
+  };
+  return workflow.rootNodeIds.flatMap(visit);
+}
+function canInspectArtifactWorkflowNode(node) {
+  return node.childIds.length === 0 && node.availability !== "unavailable";
+}
+function assertArtifactWorkflow(workflow) {
+  if (workflow.schemaVersion !== 1)
+    throw new Error("Unsupported artifact workflow schema");
+  if (!Number.isSafeInteger(workflow.revision) || workflow.revision < 1) {
+    throw new Error("Artifact workflow revision must be a positive integer");
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const nodes = [];
+  const visit = (id, expectedParentId) => {
+    const node = workflow.nodesById[id];
+    if (!node) throw new Error(`Artifact workflow node ${id} does not exist`);
+    if (visiting.has(id)) throw new Error("Artifact workflow contains a cycle");
+    if (visited.has(id))
+      throw new Error("Artifact workflow contains a duplicate node reference");
+    if (node.parentId !== expectedParentId) {
+      throw new Error(`Artifact workflow node ${id} has an invalid parent`);
+    }
+    visiting.add(id);
+    nodes.push(node);
+    node.childIds.forEach((childId) => visit(childId, id));
+    visiting.delete(id);
+    visited.add(id);
+  };
+  workflow.rootNodeIds.forEach((id) => visit(id, null));
+  if (visited.size !== Object.keys(workflow.nodesById).length) {
+    throw new Error("Artifact workflow contains unreachable nodes");
+  }
+  if (workflow.currentNodeId && !workflow.nodesById[workflow.currentNodeId]) {
+    throw new Error("Artifact workflow current node does not exist");
+  }
+  const currentNode = workflow.currentNodeId ? workflow.nodesById[workflow.currentNodeId] : null;
+  if (currentNode && currentNode.childIds.length > 0) {
+    throw new Error("Artifact workflow current node must be actionable leaf");
+  }
+  const actionable = nodes.filter(
+    (node) => isArtifactWorkflowNodeNavigableLeaf(workflow, node) && isArtifactWorkflowNodeActionable(node)
+  );
+  if (actionable.length > 1)
+    throw new Error("Artifact workflow has multiple current nodes");
+  if (actionable.length === 1 && actionable[0].id !== workflow.currentNodeId) {
+    throw new Error("Artifact workflow current node does not own its action");
+  }
+  if (workflow.currentNodeId && !actionable.length && !isArtifactWorkflowNodeTerminal(currentNode)) {
+    throw new Error("Artifact workflow current node is not actionable");
+  }
+}
+function requireArtifactWorkflow(artifact) {
+  if (!artifact.workflow) {
+    throw new Error(
+      `Artifact ${artifact.artifactId} has no canonical workflow`
+    );
+  }
+  assertArtifactWorkflow(artifact.workflow);
+  if (artifact.workflow.artifactId !== artifact.artifactId) {
+    throw new Error("Artifact workflow belongs to a different artifact");
+  }
+  return artifact;
+}
+function requireArtifactWorkflowResult(result) {
+  requireArtifactWorkflow(result.artifact);
+  return result;
+}
+
 // src/client.ts
 var DEFAULT_CONVERSATION_SESSION_LIST_LIMIT = 100;
 var MAX_CONVERSATION_SESSION_LIST_LIMIT = 500;
@@ -16137,17 +17047,17 @@ function planRecordObjectsChunks(records, batchSize) {
   }
   return plans;
 }
-function preserveRecordObjectRealId(record) {
-  const realId = record.id.trim();
+function preserveRecordObjectRealId(record2) {
+  const realId = record2.id.trim();
   if (!realId) {
-    return record;
+    return record2;
   }
-  const fields = record.fields || {};
+  const fields = record2.fields || {};
   if (typeof fields.real_id === "string" && fields.real_id.trim()) {
-    return record;
+    return record2;
   }
   return {
-    ...record,
+    ...record2,
     fields: {
       ...fields,
       real_id: realId
@@ -16479,7 +17389,7 @@ var Environment = class _Environment {
   }
   get data() {
     return {
-      record: async (record) => this.recordObject(record),
+      record: async (record2) => this.recordObject(record2),
       recordMany: async (records, options) => this.recordObjects(records, options),
       import: async (records, options) => this.enqueueRecordImport(records, options),
       listImports: async (status) => this.listRecordImports(status),
@@ -17827,6 +18737,7 @@ var EnvironmentSession = class extends Session {
   sessionDataHeaders;
   beforeMutationSend;
   heartbeatTimer = null;
+  heartbeatProbeInFlight = false;
   /** The last known graph container status, updated by checkReadiness(). */
   graphContainerStatus = null;
   constructor(client, environment, clientId, options = {}) {
@@ -17846,16 +18757,34 @@ var EnvironmentSession = class extends Session {
    * an application RPC may be delayed by Durable Object work even while the
    * underlying WebSocket is healthy.
    */
-  startHeartbeat() {
+  startHeartbeat(options = {}) {
     if (this.heartbeatTimer) return;
-    this.heartbeatTimer = setInterval(() => {
-      if (!this.client.isTransportOpen()) return;
-      if (this.client.hasRecentInboundActivity(3e4)) return;
-      if (this.client.hasRecentlyPendingRpcPeriod(6e4)) return;
-      this.client.reportTransportFailure(
-        new Error("No server activity received for 30 seconds")
-      );
-    }, 5e3);
+    const probeServer = options.probeServer === true;
+    this.heartbeatTimer = setInterval(
+      () => {
+        if (!this.client.isTransportOpen()) return;
+        if (probeServer) {
+          if (this.heartbeatProbeInFlight) return;
+          if (this.client.hasPendingRpcRequests()) return;
+          if (this.client.hasRecentInboundActivity(1e4)) return;
+          this.heartbeatProbeInFlight = true;
+          void this.client.call("client.heartbeat", {}).catch((error) => {
+            if (this.client.isTransportOpen()) {
+              this.client.reportTransportFailure(error);
+            }
+          }).finally(() => {
+            this.heartbeatProbeInFlight = false;
+          });
+          return;
+        }
+        if (this.client.hasRecentInboundActivity(3e4)) return;
+        if (this.client.hasRecentlyPendingRpcPeriod(6e4)) return;
+        this.client.reportTransportFailure(
+          new Error("No server activity received for 30 seconds")
+        );
+      },
+      probeServer ? 1e4 : 5e3
+    );
     this.heartbeatTimer.unref?.();
   }
   stopHeartbeat() {
@@ -17863,10 +18792,15 @@ var EnvironmentSession = class extends Session {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
     }
+    this.heartbeatProbeInFlight = false;
   }
   async hello() {
     const result = await super.hello();
-    this.startHeartbeat();
+    if (result.features?.serverHeartbeat === false) {
+      this.startHeartbeat({ probeServer: true });
+    } else {
+      this.startHeartbeat();
+    }
     return result;
   }
   get environmentId() {
@@ -18001,13 +18935,13 @@ var EnvironmentSession = class extends Session {
       input.operationId,
       "operationId"
     );
-    const text = requiredAssistantReplyString(input.text, "text");
+    const text2 = requiredAssistantReplyString(input.text, "text");
     return this.sessionDataRequest(
       "/assistant-replies",
       void 0,
       {
         method: "POST",
-        body: { id, operationId: operationId2, text }
+        body: { id, operationId: operationId2, text: text2 }
       }
     );
   }
@@ -18052,7 +18986,10 @@ var EnvironmentSession = class extends Session {
           queryOptions.targetId = options.target.id;
           delete queryOptions.target;
         }
-        return this.sessionDataRequest("/artifacts", queryOptions);
+        return this.sessionDataRequest("/artifacts", queryOptions).then((page) => ({
+          ...page,
+          items: page.items.map(requireArtifactWorkflow)
+        }));
       },
       listForLatestJob: (options = {}) => this.artifacts.list({
         ...options,
@@ -18065,7 +19002,7 @@ var EnvironmentSession = class extends Session {
         // `cache: no-store`; this also bypasses intermediaries that ignore
         // the Fetch cache directive for an otherwise identical GET URL.
         { _granularLiveRead: Date.now() }
-      ),
+      ).then(requireArtifactWorkflow),
       create: (artifact) => this.sessionDataRequest(
         "/artifacts",
         void 0,
@@ -18073,7 +19010,7 @@ var EnvironmentSession = class extends Session {
           method: "POST",
           body: artifact
         }
-      ),
+      ).then(requireArtifactWorkflow),
       acceptSuggestion: (sequence) => this.sessionDataRequest(
         "/artifacts/suggestions/accept",
         void 0,
@@ -18081,7 +19018,7 @@ var EnvironmentSession = class extends Session {
           method: "POST",
           body: { sequence }
         }
-      ),
+      ).then(requireArtifactWorkflow),
       updateInputs: (artifactId, patch) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}`,
         void 0,
@@ -18089,7 +19026,7 @@ var EnvironmentSession = class extends Session {
           method: "PATCH",
           body: patch
         }
-      ),
+      ).then(requireArtifactWorkflow),
       relationshipOptions: (artifactId, input) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/relationship-options`,
         void 0,
@@ -18099,27 +19036,27 @@ var EnvironmentSession = class extends Session {
         `/artifacts/${encodeURIComponent(artifactId)}/relationship-create`,
         void 0,
         { method: "POST", body: input }
-      ),
+      ).then(requireArtifactWorkflow),
       validate: (artifactId) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/validate`,
         void 0,
         { method: "POST" }
-      ),
+      ).then(requireArtifactWorkflowResult),
       execute: (artifactId, options) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/execute`,
         void 0,
         { method: "POST", body: options }
-      ),
+      ).then(requireArtifactWorkflowResult),
       approve: (artifactId, options) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/approve`,
         void 0,
         { method: "POST", body: options }
-      ),
+      ).then(requireArtifactWorkflowResult),
       cancel: (artifactId) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/cancel`,
         void 0,
         { method: "POST" }
-      )
+      ).then(requireArtifactWorkflow)
     };
   }
   get manualActions() {
@@ -20107,13 +21044,13 @@ var Granular = class _Granular {
    * Permission Profile management for sandboxes
    */
   get permissionProfiles() {
-    const profileSourceFromRecord = (record) => {
-      const profile = record.profile || record.rules || {};
+    const profileSourceFromRecord = (record2) => {
+      const profile = record2.profile || record2.rules || {};
       return {
         ...profile,
         schemaVersion: profile.schemaVersion || 1,
-        name: profile.name || record.name,
-        description: profile.description || record.description
+        name: profile.name || record2.name,
+        description: profile.description || record2.description
       };
     };
     return {
@@ -20696,18 +21633,18 @@ function stableValue(value) {
 function stableJson(value) {
   return JSON.stringify(stableValue(value));
 }
-function recordKey(record) {
-  return `${record.className}\0${record.id}`;
+function recordKey(record2) {
+  return `${record2.className}\0${record2.id}`;
 }
 function recordReference(className, id) {
   return { className, id };
 }
 function changedRecordSnapshots(beforeRecords, afterRecords) {
   const before = new Map(
-    beforeRecords.map((record) => [recordKey(record), record])
+    beforeRecords.map((record2) => [recordKey(record2), record2])
   );
   const after = new Map(
-    afterRecords.map((record) => [recordKey(record), record])
+    afterRecords.map((record2) => [recordKey(record2), record2])
   );
   const changedKeys = /* @__PURE__ */ new Set();
   for (const key of /* @__PURE__ */ new Set([...before.keys(), ...after.keys()])) {
@@ -20717,10 +21654,10 @@ function changedRecordSnapshots(beforeRecords, afterRecords) {
   }
   return {
     beforeRecords: beforeRecords.filter(
-      (record) => changedKeys.has(recordKey(record))
+      (record2) => changedKeys.has(recordKey(record2))
     ),
     afterRecords: afterRecords.filter(
-      (record) => changedKeys.has(recordKey(record))
+      (record2) => changedKeys.has(recordKey(record2))
     )
   };
 }
@@ -20769,35 +21706,35 @@ function changedObjectProjection(before, after) {
 }
 function projectionChanges(input) {
   const before = new Map(
-    input.beforeRecords.map((record) => [recordKey(record), record])
+    input.beforeRecords.map((record2) => [recordKey(record2), record2])
   );
   const after = new Map(
-    input.afterRecords.map((record) => [recordKey(record), record])
+    input.afterRecords.map((record2) => [recordKey(record2), record2])
   );
   const targets = relationshipTargets(input.manifest);
   const changes = [];
-  for (const record of input.afterRecords) {
-    const previous = before.get(recordKey(record));
-    const objectChange = changedObjectProjection(previous, record);
+  for (const record2 of input.afterRecords) {
+    const previous = before.get(recordKey(record2));
+    const objectChange = changedObjectProjection(previous, record2);
     if (objectChange) changes.push(objectChange);
     const relationshipNames = /* @__PURE__ */ new Set([
       ...Object.keys(previous?.relationships || {}),
-      ...Object.keys(record.relationships || {})
+      ...Object.keys(record2.relationships || {})
     ]);
     for (const relationshipName of [...relationshipNames].sort()) {
       const target = targets.get(
-        `${record.className}\0${relationshipName}`
+        `${record2.className}\0${relationshipName}`
       );
       if (!target) {
         throw new Error(
-          `No ontology relationship target is declared for ${record.className}.${relationshipName}`
+          `No ontology relationship target is declared for ${record2.className}.${relationshipName}`
         );
       }
       const previousIds = new Set(
         asIds(previous?.relationships?.[relationshipName])
       );
       const currentIds = new Set(
-        asIds(record.relationships?.[relationshipName])
+        asIds(record2.relationships?.[relationshipName])
       );
       for (const id of [...previousIds].sort()) {
         if (currentIds.has(id)) continue;
@@ -20805,7 +21742,7 @@ function projectionChanges(input) {
           kind: "relationship",
           operation: "disconnected",
           relationship: relationshipName,
-          from: recordReference(record.className, record.id),
+          from: recordReference(record2.className, record2.id),
           to: recordReference(target.className, id)
         });
       }
@@ -20815,37 +21752,37 @@ function projectionChanges(input) {
           kind: "relationship",
           operation: "connected",
           relationship: relationshipName,
-          from: recordReference(record.className, record.id),
+          from: recordReference(record2.className, record2.id),
           to: recordReference(target.className, id)
         });
       }
     }
     const machines = /* @__PURE__ */ new Set([
       ...Object.keys(previous?.states || {}),
-      ...Object.keys(record.states || {})
+      ...Object.keys(record2.states || {})
     ]);
     for (const machine of [...machines].sort()) {
-      const next = record.states?.[machine];
+      const next = record2.states?.[machine];
       if (next === void 0) continue;
       const prior = previous?.states?.[machine];
       if (prior !== void 0 && stateName(prior) === stateName(next)) continue;
-      if (input.transition && input.transition.className === record.className && input.transition.objectId === record.id && input.transition.machine === machine) {
+      if (input.transition && input.transition.className === record2.className && input.transition.objectId === record2.id && input.transition.machine === machine) {
         continue;
       }
       changes.push({
         kind: "state_observation",
-        target: recordReference(record.className, record.id),
+        target: recordReference(record2.className, record2.id),
         machine,
         state: stateName(next)
       });
     }
   }
-  for (const record of input.beforeRecords) {
-    if (after.has(recordKey(record))) continue;
+  for (const record2 of input.beforeRecords) {
+    if (after.has(recordKey(record2))) continue;
     changes.push({
       kind: "object",
       operation: "deleted",
-      target: recordReference(record.className, record.id)
+      target: recordReference(record2.className, record2.id)
     });
   }
   return changes;
@@ -20890,7 +21827,7 @@ function transitionOutcome(transition, afterRecords) {
     throw new Error("A transition commit has no authored transition context.");
   }
   const target = afterRecords.find(
-    (record) => record.className === transition.className && record.id === transition.objectId
+    (record2) => record2.className === transition.className && record2.id === transition.objectId
   );
   const observed = target?.states?.[transition.machine];
   if (!observed) {
@@ -20936,7 +21873,8 @@ function projectRecordSnapshotMutation(input) {
   const base = {
     source: {
       reference: input.source.reference,
-      ...input.source.version ? { version: input.source.version } : {}
+      ...input.source.version ? { version: input.source.version } : {},
+      ...input.source.versionScope ? { versionScope: input.source.versionScope } : {}
     },
     ...target ? { primaryTarget: target } : {},
     changes,
@@ -21107,29 +22045,29 @@ function requireRecord(value, context) {
   }
   return value;
 }
-function requiredString(record, key, context) {
-  const value = record[key];
+function requiredString(record2, key, context) {
+  const value = record2[key];
   if (typeof value !== "string" || !value.trim()) {
     throw new Error(`${context}.${key} must be a non-empty string.`);
   }
   return value;
 }
-function requiredNumber(record, key, context) {
-  const value = record[key];
+function requiredNumber(record2, key, context) {
+  const value = record2[key];
   if (typeof value !== "number" || !Number.isFinite(value)) {
     throw new Error(`${context}.${key} must be a finite number.`);
   }
   return value;
 }
-function requiredStringArray(record, key, context) {
-  const value = record[key];
+function requiredStringArray(record2, key, context) {
+  const value = record2[key];
   if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || !item.trim())) {
     throw new Error(`${context}.${key} must be an array of non-empty strings.`);
   }
   return [...value];
 }
-function requiredNumberRecord(record, key, context) {
-  const value = requireRecord(record[key], `${context}.${key}`);
+function requiredNumberRecord(record2, key, context) {
+  const value = requireRecord(record2[key], `${context}.${key}`);
   const output = {};
   for (const [entryKey, entryValue] of Object.entries(value)) {
     if (typeof entryValue !== "number" || !Number.isFinite(entryValue) || entryValue < 0 || entryValue > 1) {
@@ -21142,22 +22080,22 @@ function requiredNumberRecord(record, key, context) {
   return output;
 }
 function validateHarnessTemplateManifest(value, context = "HarnessTemplateManifest") {
-  const record = requireRecord(value, context);
-  const status = requiredString(record, "status", context);
+  const record2 = requireRecord(value, context);
+  const status = requiredString(record2, "status", context);
   if (!HARNESS_TEMPLATE_STATUSES.includes(status)) {
     throw new Error(
       `${context}.status must be one of ${HARNESS_TEMPLATE_STATUSES.join(", ")}.`
     );
   }
-  const createdAt = requiredString(record, "createdAt", context);
+  const createdAt = requiredString(record2, "createdAt", context);
   if (Number.isNaN(Date.parse(createdAt))) {
     throw new Error(`${context}.createdAt must be an ISO timestamp.`);
   }
   const compatibility = requireRecord(
-    record.compatibility,
+    record2.compatibility,
     `${context}.compatibility`
   );
-  const evalGates = requireRecord(record.evalGates, `${context}.evalGates`);
+  const evalGates = requireRecord(record2.evalGates, `${context}.evalGates`);
   const maxRegressionPct = requiredNumber(
     evalGates,
     "maxRegressionPct",
@@ -21169,23 +22107,23 @@ function validateHarnessTemplateManifest(value, context = "HarnessTemplateManife
     );
   }
   return {
-    id: requiredString(record, "id", context),
-    version: requiredString(record, "version", context),
+    id: requiredString(record2, "id", context),
+    version: requiredString(record2, "version", context),
     status,
-    owner: requiredString(record, "owner", context),
+    owner: requiredString(record2, "owner", context),
     createdAt,
-    changelog: requiredString(record, "changelog", context),
-    promptBuilder: requiredString(record, "promptBuilder", context),
-    continuationBuilder: requiredString(record, "continuationBuilder", context),
+    changelog: requiredString(record2, "changelog", context),
+    promptBuilder: requiredString(record2, "promptBuilder", context),
+    continuationBuilder: requiredString(record2, "continuationBuilder", context),
     modelOutputInstruction: requiredString(
-      record,
+      record2,
       "modelOutputInstruction",
       context
     ),
-    codeReviewPolicy: requiredString(record, "codeReviewPolicy", context),
-    defaultModel: requiredString(record, "defaultModel", context),
-    modelMatrix: requiredStringArray(record, "modelMatrix", context),
-    temperature: requiredNumber(record, "temperature", context),
+    codeReviewPolicy: requiredString(record2, "codeReviewPolicy", context),
+    defaultModel: requiredString(record2, "defaultModel", context),
+    modelMatrix: requiredStringArray(record2, "modelMatrix", context),
+    temperature: requiredNumber(record2, "temperature", context),
     compatibility: {
       minSdkVersion: requiredString(
         compatibility,
@@ -21239,27 +22177,27 @@ var DEFAULT_LOW_SIGNAL_REASONING_LINES = [
 function parseReasoningCommentLine(line, options = {}) {
   const trimmed = line.trimStart();
   if (!trimmed.startsWith("//")) return null;
-  const text = trimmed.replace(/^\/\/\s?/, "").trim();
-  if (!text) return { kind: "ignored" };
+  const text2 = trimmed.replace(/^\/\/\s?/, "").trim();
+  if (!text2) return { kind: "ignored" };
   const ignoredDirectives = options.ignoredCommentDirectives || DEFAULT_IGNORED_REASONING_COMMENT_DIRECTIVES;
-  if (ignoredDirectives.some((pattern) => pattern.test(text))) {
+  if (ignoredDirectives.some((pattern) => pattern.test(text2))) {
     return { kind: "ignored" };
   }
   const lowSignalLines = options.lowSignalReasoningLines || DEFAULT_LOW_SIGNAL_REASONING_LINES;
-  if (lowSignalLines.some((pattern) => pattern.test(text))) {
+  if (lowSignalLines.some((pattern) => pattern.test(text2))) {
     return { kind: "ignored" };
   }
-  return { kind: "reasoning", text };
+  return { kind: "reasoning", text: text2 };
 }
 function consumeGranularReasoningTraceChunk(buffer, chunk, options = {}) {
-  let text = buffer + chunk;
+  let text2 = buffer + chunk;
   let visibleText = "";
   const reasoningLines = [];
   while (true) {
-    const newlineIndex = text.indexOf("\n");
+    const newlineIndex = text2.indexOf("\n");
     if (newlineIndex === -1) break;
-    const rawLine = text.slice(0, newlineIndex);
-    text = text.slice(newlineIndex + 1);
+    const rawLine = text2.slice(0, newlineIndex);
+    text2 = text2.slice(newlineIndex + 1);
     const comment = parseReasoningCommentLine(
       rawLine.replace(/\r$/, ""),
       options
@@ -21273,19 +22211,19 @@ function consumeGranularReasoningTraceChunk(buffer, chunk, options = {}) {
 `;
     }
   }
-  if (options.final && text.length > 0) {
-    const comment = parseReasoningCommentLine(text.replace(/\r$/, ""), options);
+  if (options.final && text2.length > 0) {
+    const comment = parseReasoningCommentLine(text2.replace(/\r$/, ""), options);
     if (comment?.kind === "reasoning") {
       reasoningLines.push(comment.text);
-      text = "";
+      text2 = "";
     } else if (comment?.kind === "ignored") {
-      text = "";
+      text2 = "";
     } else {
-      visibleText += text;
-      text = "";
+      visibleText += text2;
+      text2 = "";
     }
   }
-  return { buffer: text, visibleText, reasoningLines };
+  return { buffer: text2, visibleText, reasoningLines };
 }
 function consumeGranularReasoningOnlyChunk(buffer, chunk, options = {}) {
   const result = consumeGranularReasoningTraceChunk(buffer, chunk, options);
@@ -21294,8 +22232,8 @@ function consumeGranularReasoningOnlyChunk(buffer, chunk, options = {}) {
     reasoningLines: result.reasoningLines
   };
 }
-function stripGranularReasoningTrace(text, options = {}) {
-  return consumeGranularReasoningTraceChunk("", text, {
+function stripGranularReasoningTrace(text2, options = {}) {
+  return consumeGranularReasoningTraceChunk("", text2, {
     ...options,
     final: true
   }).visibleText.trim();
@@ -21330,8 +22268,8 @@ function stableStringify(value) {
   if (Array.isArray(value)) {
     return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
   }
-  const record = value;
-  return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+  const record2 = value;
+  return `{${Object.keys(record2).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record2[key])}`).join(",")}}`;
 }
 function renderConstBlock(name, value) {
   return `const ${name} = ${JSON.stringify(value, null, 2)} as const;`;
@@ -21927,9 +22865,9 @@ function getLatestClosure(liveDoc) {
   }
   const closures = [];
   for (const [closureId, value] of Object.entries(closuresById)) {
-    const record = asRecord4(value);
-    if (!record) continue;
-    closures.push({ ...record, closureId });
+    const record2 = asRecord4(value);
+    if (!record2) continue;
+    closures.push({ ...record2, closureId });
   }
   closures.sort(
     (left, right) => (Number(right.createdAt) || 0) - (Number(left.createdAt) || 0)
@@ -21967,9 +22905,9 @@ function getJobRecords(liveDoc) {
   const jobsById = asRecord4(asRecord4(liveDoc?.jobs)?.byId) || {};
   const jobs = [];
   for (const [jobId, value] of Object.entries(jobsById)) {
-    const record = asRecord4(value);
-    if (!record) continue;
-    jobs.push({ ...record, jobId });
+    const record2 = asRecord4(value);
+    if (!record2) continue;
+    jobs.push({ ...record2, jobId });
   }
   jobs.sort(
     (left, right) => getJobTimestamp(right) - getJobTimestamp(left)
@@ -22155,8 +23093,8 @@ function hasOpenPrompt(liveDoc, pendingPrompts) {
     const prompts = asRecord4(asRecord4(job)?.prompts);
     if (!prompts) continue;
     for (const prompt of Object.values(prompts)) {
-      const record = asRecord4(prompt);
-      if (record?.status === "open") return true;
+      const record2 = asRecord4(prompt);
+      if (record2?.status === "open") return true;
     }
   }
   return false;
@@ -22215,13 +23153,13 @@ function projectLoopSummary(liveDoc, pendingPrompts = [], options) {
       title: typeof decision.title === "string" && decision.title.trim() ? decision.title.trim() : "Decision",
       status,
       candidates: status === "open" ? asArray(decision.candidates).slice(0, 5).map((candidate) => {
-        const record = asRecord4(candidate);
-        if (!record) return null;
+        const record2 = asRecord4(candidate);
+        if (!record2) return null;
         return {
-          id: typeof record.id === "string" ? record.id : "unknown",
-          label: typeof record.label === "string" && record.label.trim() ? record.label.trim() : null,
-          description: typeof record.description === "string" && record.description.trim() ? record.description.trim() : null,
-          metadata: asRecord4(record.metadata)
+          id: typeof record2.id === "string" ? record2.id : "unknown",
+          label: typeof record2.label === "string" && record2.label.trim() ? record2.label.trim() : null,
+          description: typeof record2.description === "string" && record2.description.trim() ? record2.description.trim() : null,
+          metadata: asRecord4(record2.metadata)
         };
       }).filter(Boolean) : [],
       selected: status === "open" ? null : {
@@ -22856,11 +23794,11 @@ function normalizeJsonSchema(value) {
   return asRecord4(value);
 }
 function jsonSchemaTypeName(schema) {
-  const record = normalizeJsonSchema(schema);
-  if (!record) return "unknown";
-  const type = record.type;
-  if (record.format === "date-time") return "date-time";
-  if (record.format === "date" || type === "date" || Array.isArray(type) && type.includes("date")) {
+  const record2 = normalizeJsonSchema(schema);
+  if (!record2) return "unknown";
+  const type = record2.type;
+  if (record2.format === "date-time") return "date-time";
+  if (record2.format === "date" || type === "date" || Array.isArray(type) && type.includes("date")) {
     return "date";
   }
   if (typeof type === "string") {
@@ -22871,12 +23809,12 @@ function jsonSchemaTypeName(schema) {
   return "unknown";
 }
 function summarizeObjectSchema(schema) {
-  const record = normalizeJsonSchema(schema);
-  const properties = asRecord4(record?.properties);
+  const record2 = normalizeJsonSchema(schema);
+  const properties = asRecord4(record2?.properties);
   if (!properties || Object.keys(properties).length === 0) {
-    return record ? "{}" : null;
+    return record2 ? "{}" : null;
   }
-  const required = new Set(asArray(record?.required));
+  const required = new Set(asArray(record2?.required));
   const fields = Object.entries(properties).slice(0, 8).map(([name, property]) => {
     const marker = required.has(name) ? "*" : "?";
     return `${name}${marker}: ${jsonSchemaTypeName(property)}`;
@@ -23365,6 +24303,10 @@ ${actionIndex}
 - Use suggestions when the user asks "what can I do next?", asks for options, or gives an unclear intent. Prefer 2 to 5 concrete suggestions and keep text short.
 - Opening a prepared action does not execute the underlying mutation. Use \`.open()\` only when the user asks to prepare, review, show, or edit an action before running it, when a new record must be prepared, or when a reviewable form must collect missing editable inputs. Prefill only grounded values and leave unknown fields empty.
 - For creation inputs, use the declared action schema and its field descriptions as the mapping authority. Copy every compatible value explicitly present in the current request, conversation, selected/saved object, file, fresh read, or declared ontology default, including values for fields with arbitrary names. Omit only values for which that context provides no evidence.
+- Preserve explicit qualifiers from the user's requested object identity, including quantities, product names, and named organizational scope. Do not shorten a title in a way that drops those qualifiers when they distinguish what is being created.
+- A contextual or ontology default may fill a value only when the user supplied no conflicting intent for that semantic role. If the user names a team, owner, account, location, or other scope that cannot be grounded, leave that relationship unresolved; never substitute the current actor's default or another convenient visible record.
+- A missing or inaccessible required relationship is not a reason to replace a reviewable action with a lookup-failure reply. Call the reviewable action with every grounded non-relationship value, omit the unresolved relationship, and let the artifact collect it from the user. This applies even when the user explicitly named the unavailable relationship.
+- Choose enum values from the request's meaning and the ontology-authored option semantics. Do not choose an enum merely because it makes an available default relationship, budget, policy, or downstream option compatible. If no enum is semantically supported, leave it unresolved or ask.
 - Never fill an input because of its field name, a regular expression or other string pattern, its primitive type, a schema minimum, an example value, or the first enum option. If the evidence is ambiguous, leave the field unresolved or ask the user.
 - When the user explicitly commands an existing-record mutation such as approve, reject, block, route, send, or update, and one visible domain action uniquely matches, call that domain action directly. Do not substitute a state-handle \`.open()\` artifact for execution. If runtime policy requires confirmation, invoke the action once and let the runtime pause and resume that same invocation.
 - When a grounded related/context record can satisfy the prepared action through declared relationships, use those relationships to fill required relationship inputs before opening or updating the action. If a required relationship remains empty, continue through declared relationship chains from the grounded object when the next hop can fill that slot. Do not only save the context record in memory while leaving derivable relationship slots blank.
@@ -23618,10 +24560,10 @@ function responseTextFromFeedItems(feedItems, jobId) {
     if (item.kind !== "message" || item.payload.role !== "assistant" || item.source?.jobId !== jobId || item.sequence <= latestSequence) {
       continue;
     }
-    const text = item.payload.text.trim();
-    if (!text) continue;
+    const text2 = item.payload.text.trim();
+    if (!text2) continue;
     latestSequence = item.sequence;
-    latestText = text;
+    latestText = text2;
   }
   return latestText;
 }
@@ -23636,39 +24578,39 @@ function pushStringArray(target, value) {
     pushString(target, item);
   }
 }
-function collectReferencesFromRecord(record, refs) {
+function collectReferencesFromRecord(record2, refs) {
   for (const key of ENTRY_KEY_CANDIDATES)
-    pushString(refs.entryPaths, record[key]);
+    pushString(refs.entryPaths, record2[key]);
   for (const key of ENTRY_ARRAY_KEY_CANDIDATES)
-    pushStringArray(refs.entryPaths, record[key]);
+    pushStringArray(refs.entryPaths, record2[key]);
   for (const key of LIST_KEY_CANDIDATES)
-    pushString(refs.listNames, record[key]);
+    pushString(refs.listNames, record2[key]);
   for (const key of LIST_ARRAY_KEY_CANDIDATES)
-    pushStringArray(refs.listNames, record[key]);
+    pushStringArray(refs.listNames, record2[key]);
   for (const key of VARIABLE_KEY_CANDIDATES)
-    pushString(refs.variableNames, record[key]);
+    pushString(refs.variableNames, record2[key]);
   for (const key of VARIABLE_ARRAY_KEY_CANDIDATES)
-    pushStringArray(refs.variableNames, record[key]);
+    pushStringArray(refs.variableNames, record2[key]);
 }
-function stringValue(record, keys) {
+function stringValue(record2, keys) {
   for (const key of keys) {
-    const value = record[key];
+    const value = record2[key];
     if (typeof value === "string" && value.trim()) {
       return value.trim();
     }
   }
   return null;
 }
-function findEntryPathForRecord(record, heap) {
-  const directPath = stringValue(record, ["entryPath", "path"]);
+function findEntryPathForRecord(record2, heap) {
+  const directPath = stringValue(record2, ["entryPath", "path"]);
   if (directPath && heap.entriesByPath?.[directPath]) {
     return directPath;
   }
-  const id = stringValue(record, ["id", "_id", "recordId", "objectId"]);
+  const id = stringValue(record2, ["id", "_id", "recordId", "objectId"]);
   if (!id) {
     return null;
   }
-  const className = stringValue(record, [
+  const className = stringValue(record2, [
     "className",
     "_className",
     "__className",
@@ -23702,17 +24644,17 @@ function scanForHeapReferences(value, heap, refs, depth = 0, seen = /* @__PURE__
     }
     return;
   }
-  const record = asRecord5(value);
-  if (!record) return;
+  const record2 = asRecord5(value);
+  if (!record2) return;
   seen.add(value);
-  const entryPath = findEntryPathForRecord(record, heap);
+  const entryPath = findEntryPathForRecord(record2, heap);
   if (entryPath) refs.entryPaths.add(entryPath);
-  collectReferencesFromRecord(record, refs);
+  collectReferencesFromRecord(record2, refs);
   for (const key of UI_CONTAINER_KEYS) {
-    const nested = asRecord5(record[key]);
+    const nested = asRecord5(record2[key]);
     if (nested) collectReferencesFromRecord(nested, refs);
   }
-  for (const nested of Object.values(record).slice(0, 24)) {
+  for (const nested of Object.values(record2).slice(0, 24)) {
     scanForHeapReferences(nested, heap, refs, depth + 1, seen);
   }
 }
@@ -23861,8 +24803,8 @@ var OPENAI_MODEL_PRICING_USD_PER_MILLION = {
 function asRecord6(value) {
   return value && typeof value === "object" ? value : null;
 }
-function numberField(record, key) {
-  const value = record?.[key];
+function numberField(record2, key) {
+  const value = record2?.[key];
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 function microsPerMillion(usdPerMillion) {
@@ -23966,6 +24908,216 @@ function calculateOpenAITokenSpend(model, rawUsage) {
   };
 }
 
+// src/artifact-surface.ts
+function operationNode(workflow) {
+  return getArtifactWorkflowNodes(workflow).find(
+    (node) => node.kind === "operation"
+  ) || null;
+}
+function operationStatusLabel(phase) {
+  if (phase === "reviewing") return "Preparing";
+  if (phase === "sending") return "In progress";
+  if (phase === "synchronizing") return "Saving";
+  if (phase === "verifying") return "Verifying";
+  if (phase === "waiting_for_approval") return "Awaiting approval";
+  if (phase === "completed") return "Completed";
+  if (phase === "failed") return "Failed";
+  return null;
+}
+function action(id, label, tone, disabled, disabledReason = null) {
+  return { id, label, tone, disabled, disabledReason };
+}
+function navigationIsUseful(workflow) {
+  const nodes = getArtifactWorkflowNodes(workflow).filter(
+    (node) => node.kind !== "operation" && node.kind !== "group"
+  );
+  return nodes.length > 1 || nodes.some((node) => node.kind === "child_artifact");
+}
+function inputNode(workflow, activeEditorNodeId) {
+  if (activeEditorNodeId) {
+    const active = workflow.nodesById[activeEditorNodeId];
+    if (active && (active.kind === "input" || active.kind === "relationship")) {
+      return active;
+    }
+  }
+  const current = getCurrentArtifactWorkflowNode(workflow);
+  return current?.kind === "input" || current?.kind === "relationship" ? current : null;
+}
+function selectArtifactSurface(artifact, context = {}) {
+  const workflow = artifact.workflow || projectArtifactWorkflow(artifact);
+  const operation = operationNode(workflow);
+  const workflowStatus = operation?.status || null;
+  const terminal = workflowStatus === "completed" || workflowStatus === "canceled";
+  const requestedEditorNodeId = terminal ? null : context.activeEditorNodeId || null;
+  const current = getCurrentArtifactWorkflowNode(workflow);
+  const activeInput = inputNode(workflow, requestedEditorNodeId);
+  const mutationsDisabled = context.mutationsDisabled === true;
+  const busy = Boolean(context.busyAction);
+  const disabledReason = mutationsDisabled ? "Reconnect to continue." : busy ? "This action is already in progress." : null;
+  const actionDisabled = Boolean(disabledReason);
+  const transportStatus = context.transportStatus || "connected";
+  let kind;
+  if (artifact.status === "completed" && workflowStatus === "completed") {
+    kind = "result";
+  } else if (artifact.status === "completed" && workflowStatus === "failed") {
+    kind = "failure";
+  } else if (artifact.status === "completed" && workflowStatus === "working") {
+    kind = "executing";
+  } else if (artifact.status === "completed" && workflowStatus && workflowStatus !== "canceled") {
+    kind = "blocked";
+  } else if (artifact.status === "completed") kind = "result";
+  else if (artifact.status === "canceled") kind = "canceled";
+  else if (artifact.status === "stale") kind = "stale";
+  else if (artifact.status === "partially_completed") kind = "partial";
+  else if (artifact.status === "failed" || context.directError)
+    kind = "failure";
+  else if (artifact.status === "blocked") kind = "blocked";
+  else if (artifact.status === "awaiting_human") kind = "approval";
+  else if (artifact.status === "running" || busy) kind = "executing";
+  else if (requestedEditorNodeId || artifact.status === "draft" || artifact.status === "needs_edit") {
+    kind = "input";
+  } else {
+    kind = "review";
+  }
+  let title = artifact.label;
+  let description = artifact.description || null;
+  let statusLabel = null;
+  let primaryAction = null;
+  let secondaryActions = [];
+  if (kind === "input") {
+    title = activeInput?.label || artifact.label;
+    description = activeInput?.description || artifact.description || null;
+    statusLabel = activeInput?.status === "needs_input" ? "Needs input" : null;
+    primaryAction = action(
+      "continue",
+      "Continue",
+      "primary",
+      actionDisabled,
+      disabledReason
+    );
+  } else if (kind === "review") {
+    title = artifact.label;
+    description = artifact.description || operation?.description || null;
+    primaryAction = action(
+      "execute",
+      operation?.label || "Continue",
+      "primary",
+      actionDisabled || context.canExecute === false,
+      disabledReason
+    );
+    if (context.canEdit) {
+      secondaryActions = [
+        action(
+          "edit",
+          "Edit details",
+          "secondary",
+          actionDisabled,
+          disabledReason
+        )
+      ];
+    }
+  } else if (kind === "executing") {
+    title = operation?.operationDetail || operation?.label || artifact.label;
+    description = operation?.operationDetail ? artifact.label : null;
+    statusLabel = operationStatusLabel(operation?.operationPhase) || "In progress";
+  } else if (kind === "approval") {
+    title = operation?.attention?.title || operation?.label || artifact.label;
+    description = operation?.attention?.detail || operation?.description || null;
+    statusLabel = "Awaiting approval";
+    if (context.canApprove) {
+      primaryAction = action(
+        "approve",
+        "Approve",
+        "primary",
+        actionDisabled,
+        disabledReason
+      );
+      secondaryActions = [
+        action(
+          "decline",
+          "Decline",
+          "secondary",
+          actionDisabled,
+          disabledReason
+        )
+      ];
+    }
+  } else if (kind === "failure" || kind === "blocked") {
+    const attention = current?.attention || operation?.attention;
+    title = attention?.title || artifact.label;
+    description = context.directError || attention?.detail || operation?.description || null;
+    statusLabel = kind === "failure" ? "Failed" : "Needs attention";
+    if (attention?.retryable) {
+      primaryAction = action(
+        "retry",
+        "Retry",
+        "primary",
+        actionDisabled,
+        disabledReason
+      );
+    } else if (context.canEdit) {
+      primaryAction = action(
+        "edit",
+        "Edit details",
+        "primary",
+        actionDisabled,
+        disabledReason
+      );
+    }
+  } else if (kind === "partial") {
+    title = operation?.attention?.title || artifact.label;
+    description = operation?.attention?.detail || operation?.description || null;
+    statusLabel = "Partially completed";
+    primaryAction = action(
+      "retry",
+      "Retry unfinished work",
+      "primary",
+      actionDisabled,
+      disabledReason
+    );
+  } else if (kind === "stale") {
+    title = operation?.attention?.title || artifact.label;
+    description = operation?.attention?.detail || operation?.description || null;
+    statusLabel = "Details changed";
+    primaryAction = action(
+      "refresh",
+      "Review latest details",
+      "primary",
+      actionDisabled,
+      disabledReason
+    );
+  } else if (kind === "result") {
+    title = artifact.label;
+    description = operation?.recap?.summary || artifact.description || null;
+    statusLabel = "Completed";
+    primaryAction = action("close", "Done", "primary", false);
+  } else {
+    title = artifact.label;
+    description = operation?.attention?.detail || "Nothing else will run.";
+    statusLabel = "Canceled";
+    primaryAction = action("close", "Done", "primary", false);
+  }
+  const activeNodeId = kind === "input" ? activeInput?.id || workflow.currentNodeId : workflow.currentNodeId;
+  const announcement = [statusLabel, title, description].filter((value) => Boolean(value)).join(". ");
+  return {
+    artifactId: artifact.artifactId,
+    revision: workflow.revision,
+    updatedAt: artifact.updatedAt,
+    kind,
+    title,
+    description,
+    statusLabel,
+    announcement,
+    workflow,
+    activeNodeId,
+    operationNodeId: operation?.id || null,
+    showNavigation: navigationIsUseful(workflow),
+    primaryAction,
+    secondaryActions,
+    transportStatus
+  };
+}
+
 exports.Environment = Environment;
 exports.EnvironmentSession = EnvironmentSession;
 exports.GRANULAR_FEED_DIAGNOSTIC_EVENT = GRANULAR_FEED_DIAGNOSTIC_EVENT;
@@ -23975,6 +25127,7 @@ exports.OntologyHandle = OntologyHandle;
 exports.Session = Session;
 exports.SessionFeedController = SessionFeedController;
 exports.WSClient = WSClient;
+exports.assertArtifactWorkflow = assertArtifactWorkflow;
 exports.buildContinuationInstruction = buildContinuationInstruction;
 exports.buildContinuationInstructionFromTemplate = buildContinuationInstructionFromTemplate;
 exports.buildGranularAgentCheckpointBlock = buildGranularAgentCheckpointBlock;
@@ -23995,6 +25148,7 @@ exports.buildOpenAISpendEventId = buildOpenAISpendEventId;
 exports.buildSessionTranscript = buildSessionTranscript;
 exports.buildSessionTranscriptFromFeedItems = buildSessionTranscriptFromFeedItems;
 exports.calculateOpenAITokenSpend = calculateOpenAITokenSpend;
+exports.canInspectArtifactWorkflowNode = canInspectArtifactWorkflowNode;
 exports.canonicalizeCommitValue = canonicalizeCommitValue;
 exports.changedRecordSnapshots = changedRecordSnapshots;
 exports.consumeGranularReasoningOnlyChunk = consumeGranularReasoningOnlyChunk;
@@ -24012,6 +25166,10 @@ exports.environmentSetupProgressFromResponse = environmentSetupProgressFromRespo
 exports.evaluateContinuation = evaluateContinuation;
 exports.evaluateValidationRule = evaluateValidationRule;
 exports.extractPromptTokens = extractPromptTokens;
+exports.getArtifactWorkflowNavigationLeaves = getArtifactWorkflowNavigationLeaves;
+exports.getArtifactWorkflowNavigationTarget = getArtifactWorkflowNavigationTarget;
+exports.getArtifactWorkflowNodes = getArtifactWorkflowNodes;
+exports.getCurrentArtifactWorkflowNode = getCurrentArtifactWorkflowNode;
 exports.getCurrentClosureId = getCurrentClosureId;
 exports.getDefaultHarnessTemplateId = getDefaultHarnessTemplateId;
 exports.getExclusivePromptTarget = getExclusivePromptTarget;
@@ -24020,6 +25178,8 @@ exports.hasCanonicalSessionFeedActivation = hasCanonicalSessionFeedActivation;
 exports.hasOpenPrompt = hasOpenPrompt;
 exports.hashHarnessTemplateValue = hashHarnessTemplateValue;
 exports.invokeRegisteredEffect = invokeRegisteredEffect;
+exports.isArtifactWorkflowNodeNavigableLeaf = isArtifactWorkflowNodeNavigableLeaf;
+exports.isArtifactWorkflowNodeTerminal = isArtifactWorkflowNodeTerminal;
 exports.isCanonicalSessionFeedDocument = isCanonicalSessionFeedDocument;
 exports.isGraphQLMutationDocument = isGraphQLMutationDocument;
 exports.isLocalApiUrl = isLocalApiUrl;
@@ -24036,6 +25196,7 @@ exports.normalizePromptText = normalizePromptText;
 exports.normalizePromptType = normalizePromptType;
 exports.orderTransientFeedItems = orderTransientFeedItems;
 exports.pollEnvironmentSetup = pollEnvironmentSetup;
+exports.projectArtifactWorkflow = projectArtifactWorkflow;
 exports.projectConversationReferentFocus = projectConversationReferentFocus;
 exports.projectConversationReferentSummary = projectConversationReferentSummary;
 exports.projectHeapSummary = projectHeapSummary;
@@ -24048,6 +25209,8 @@ exports.readSessionFeedSnapshot = readSessionFeedSnapshot;
 exports.recordOpenAIUsageSpend = recordOpenAIUsageSpend;
 exports.renderContinuationInstructionFromTemplate = renderContinuationInstructionFromTemplate;
 exports.renderGranularAgentSystemPromptFromTemplate = renderGranularAgentSystemPromptFromTemplate;
+exports.requireArtifactWorkflow = requireArtifactWorkflow;
+exports.requireArtifactWorkflowResult = requireArtifactWorkflowResult;
 exports.resolveApiUrl = resolveApiUrl;
 exports.resolveAuthTokenForApiUrl = resolveAuthTokenForApiUrl;
 exports.resolveHarnessTemplate = resolveHarnessTemplate;
@@ -24055,6 +25218,7 @@ exports.resolveJobPresentation = resolveJobPresentation;
 exports.resolvePromptAnswer = resolvePromptAnswer;
 exports.reviewGeneratedJobCode = reviewGeneratedJobCode;
 exports.scorePromptChoiceMatch = scorePromptChoiceMatch;
+exports.selectArtifactSurface = selectArtifactSurface;
 exports.stripGranularReasoningTrace = stripGranularReasoningTrace;
 exports.toGranularHttpBase = toGranularHttpBase;
 exports.validateHarnessTemplateManifest = validateHarnessTemplateManifest;