@granular-software/sdk 0.4.64 → 0.4.65

package/dist/cli/index.js

@@ -14167,6 +14167,12 @@ var StateTransitionExpectedOutcomeSchema = external_exports.union([
     summary: external_exports.string().optional()
   }).strict()
 ]);
+var StateTransitionOutcomeSchema = external_exports.object({
+  label: external_exports.string().min(1).optional(),
+  to: external_exports.string().min(1),
+  primary: external_exports.boolean().optional(),
+  disposition: external_exports.enum(["continue", "error"])
+}).strict();
 var StateMachineTransitionSchema = external_exports.object({
   name: external_exports.string().min(1),
   from: external_exports.string().min(1),
@@ -14178,7 +14184,8 @@ var StateMachineTransitionSchema = external_exports.object({
   requirements: StateTransitionRequirementsSchema.optional(),
   permission: StateTransitionPermissionSchema.optional(),
   risk: external_exports.enum(["low", "medium", "high"]).optional(),
-  expectedOutcome: StateTransitionExpectedOutcomeSchema.optional()
+  expectedOutcome: StateTransitionExpectedOutcomeSchema.optional(),
+  outcomes: external_exports.record(external_exports.string().min(1), StateTransitionOutcomeSchema).optional()
 }).strict();
 external_exports.object({
   name: external_exports.string().min(1),
@@ -15529,7 +15536,8 @@ function normalizeStateMachines(values) {
       requirements: parseJsonRecord(transition?.requirements) || parseJsonRecord(transition?.requirements_json),
       permission: parseJsonValue(transition?.permission) ?? parseJsonValue(transition?.permission_json),
       risk: transition?.risk === "low" || transition?.risk === "medium" || transition?.risk === "high" ? transition.risk : null,
-      expectedOutcome: parseJsonValue(transition?.expectedOutcome) ?? parseJsonValue(transition?.expected_outcome_json)
+      expectedOutcome: parseJsonValue(transition?.expectedOutcome) ?? parseJsonValue(transition?.expected_outcome_json),
+      outcomes: parseJsonRecord(transition?.outcomes) || parseJsonRecord(transition?.outcomes_json)
     })).filter(
       (transition) => transition.name.length > 0 && transition.from.length > 0 && transition.to.length > 0
     );
@@ -15622,6 +15630,11 @@ function transitionMetadataGraphqlArgs(transition) {
       `expected_outcome_json: ${JSON.stringify(JSON.stringify(transition.expectedOutcome))}`
     );
   }
+  if (transition.outcomes) {
+    args.push(
+      `outcomes_json: ${JSON.stringify(JSON.stringify(transition.outcomes))}`
+    );
+  }
   return args.length > 0 ? `, ${args.join(", ")}` : "";
 }
 function buildStateMachineModelMutations(modelPath, machines) {
@@ -15900,7 +15913,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): 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!
         activate_transition(name: String!): StateMachineMutation!
       }
 
@@ -15917,6 +15930,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
       type StateMachineSnapshotMutation {
         snapshot: StateMachineSnapshot!
         activate_transition(name: String!): StateMachineSnapshotMutation!
+        commit_transition(name: String!, outcome: String!, to: String!, commit_id: String!, source_version: String): StateMachineSnapshotMutation!
         observe_state(state: String!, force: Boolean, source: String): StateMachineSnapshotMutation!
       }
 
@@ -15963,6 +15977,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
         permission_json: String
         risk: String
         expected_outcome_json: String
+        outcomes_json: String
       }
 
       type StateMachinePath {
@@ -15973,6 +15988,10 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
       type StateMachineTransitionEvent {
         sequence: Int!
         occurred_at: Float!
+        commit_id: String
+        outcome: String
+        source_version: String
+        projected_from_mismatch: String
         transition: StateMachineTransition!
         from: StateMachineState!
         to: StateMachineState!
@@ -16038,7 +16057,8 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             requirements_json,
             permission_json,
             risk,
-            expected_outcome_json
+            expected_outcome_json,
+            outcomes_json
           }) => {
             await run(
               value.target.add_state_machine_transition(
@@ -16054,7 +16074,8 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
                   requirementsJson: requirements_json,
                   permissionJson: permission_json,
                   risk,
-                  expectedOutcomeJson: expected_outcome_json
+                  expectedOutcomeJson: expected_outcome_json,
+                  outcomesJson: outcomes_json
                 }
               )
             );
@@ -16075,6 +16096,19 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             );
             return value;
           },
+          commit_transition: async (value, { name, outcome, to, commit_id, source_version }) => {
+            await run(
+              value.target.commit_state_machine_transition(
+                value.name,
+                name,
+                outcome,
+                to,
+                commit_id,
+                source_version
+              )
+            );
+            return value;
+          },
           observe_state: async (value, { state, force, source }) => {
             await run(
               value.target.observe_state_machine_state(
@@ -16104,7 +16138,8 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
           requirements_json: (value) => value.requirements_json || null,
           permission_json: (value) => value.permission_json || null,
           risk: (value) => value.risk || null,
-          expected_outcome_json: (value) => value.expected_outcome_json || null
+          expected_outcome_json: (value) => value.expected_outcome_json || null,
+          outcomes_json: (value) => value.outcomes_json || null
         },
         StateMachinePath: {
           states: (value) => value.states,
@@ -16113,6 +16148,10 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
         StateMachineTransitionEvent: {
           sequence: (value) => value.sequence,
           occurred_at: (value) => value.occurred_at,
+          commit_id: (value) => value.commit_id || null,
+          outcome: (value) => value.outcome || null,
+          source_version: (value) => value.source_version || null,
+          projected_from_mismatch: (value) => value.projected_from_mismatch || null,
           transition: (value) => value.transition,
           from: (value) => value.from,
           to: (value) => value.to
@@ -16186,6 +16225,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             permission_json
             risk
             expected_outcome_json
+            outcomes_json
           }
         }`
       ]
@@ -22095,6 +22135,11 @@ var Session = class {
     }
   }
   buildDirectedInvocationEffectContext(params, feedbackContext) {
+    const commitUnavailable = async () => {
+      throw new Error(
+        "This directed browser tool invocation has no product commit transport"
+      );
+    };
     return {
       effectClientId: this.clientId,
       sandboxId: params.sandboxId || "",
@@ -22107,6 +22152,10 @@ var Session = class {
         userId: "",
         subjectId: ""
       },
+      commit: {
+        effect: commitUnavailable,
+        transition: commitUnavailable
+      },
       ...feedbackContext ? {
         feedback: feedbackContext.feedback,
         transientFeedback: feedbackContext.transientFeedback
@@ -23636,6 +23685,238 @@ function buildSessionTranscript(input) {
   });
 }
 
+// src/commit.ts
+var MAX_PROJECTION_CHANGES = 1e3;
+var MAX_SAFE_SUMMARY_KEYS = 32;
+var MAX_SAFE_TEXT_LENGTH = 2e3;
+var definedTransitionMetadata = /* @__PURE__ */ new WeakMap();
+function getDefinedTransitionMetadata(transition) {
+  return definedTransitionMetadata.get(transition);
+}
+function requireNonEmptyString(value, path7) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${path7} must be a non-empty string`);
+  }
+  return value.trim();
+}
+function validateObjectReference(value, path7) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${path7} must be an object reference`);
+  }
+  const reference = value;
+  requireNonEmptyString(reference.className, `${path7}.className`);
+  requireNonEmptyString(reference.id, `${path7}.id`);
+  if (reference.path !== void 0) {
+    requireNonEmptyString(reference.path, `${path7}.path`);
+  }
+}
+function validateScalarRecord(value, path7) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new Error(`${path7} must be an object of scalar values`);
+  }
+  for (const [key, item] of Object.entries(value)) {
+    if (item !== null && typeof item !== "string" && typeof item !== "number" && typeof item !== "boolean") {
+      throw new Error(
+        `${path7}.${key} must be a string, finite number, boolean, or null`
+      );
+    }
+    if (typeof item === "number" && !Number.isFinite(item)) {
+      throw new Error(`${path7}.${key} must be finite`);
+    }
+  }
+}
+function validateProjectedRecord(value, path7) {
+  validateObjectReference(value, path7);
+  const record = value;
+  if (record.label !== void 0) {
+    if (typeof record.label !== "string") {
+      throw new Error(`${path7}.label must be a string`);
+    }
+    if (record.label.length > MAX_SAFE_TEXT_LENGTH) {
+      throw new Error(
+        `${path7}.label exceeds ${MAX_SAFE_TEXT_LENGTH} characters`
+      );
+    }
+  }
+  validateScalarRecord(record.fields, `${path7}.fields`);
+}
+function validateBoundedJson(value, path7, depth = 0) {
+  if (depth > 12) throw new Error(`${path7} is nested too deeply`);
+  if (value === null || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`${path7} must be finite`);
+    return;
+  }
+  if (typeof value === "string") {
+    if (value.length > MAX_SAFE_TEXT_LENGTH) {
+      throw new Error(`${path7} exceeds ${MAX_SAFE_TEXT_LENGTH} characters`);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > MAX_PROJECTION_CHANGES) {
+      throw new Error(`${path7} contains too many values`);
+    }
+    value.forEach(
+      (item, index) => validateBoundedJson(item, `${path7}[${index}]`, depth + 1)
+    );
+    return;
+  }
+  if (!value || typeof value !== "object") {
+    throw new Error(`${path7} contains an unsupported value`);
+  }
+  const entries = Object.entries(value);
+  if (entries.length > 256) throw new Error(`${path7} contains too many keys`);
+  for (const [key, item] of entries) {
+    if (/token|secret|password|authorization|cookie/i.test(key)) {
+      throw new Error(`${path7}.${key} is not allowed in a commit projection`);
+    }
+    validateBoundedJson(item, `${path7}.${key}`, depth + 1);
+  }
+}
+function validateProjectionResult(declaration, projection) {
+  if (!projection || typeof projection !== "object") {
+    throw new Error("Projection mapper must return an object");
+  }
+  requireNonEmptyString(
+    projection.source?.reference,
+    "projection.source.reference"
+  );
+  if (projection.source.version !== void 0) {
+    requireNonEmptyString(
+      projection.source.version,
+      "projection.source.version"
+    );
+  }
+  if (!Array.isArray(projection.changes)) {
+    throw new Error("projection.changes must be an array");
+  }
+  if (projection.changes.length > MAX_PROJECTION_CHANGES) {
+    throw new Error(
+      `projection.changes exceeds the ${MAX_PROJECTION_CHANGES} change limit`
+    );
+  }
+  if (projection.primaryTarget) {
+    validateObjectReference(
+      projection.primaryTarget,
+      "projection.primaryTarget"
+    );
+  }
+  if (projection.safeSummary) {
+    const entries = Object.entries(projection.safeSummary);
+    if (entries.length > MAX_SAFE_SUMMARY_KEYS) {
+      throw new Error(
+        `projection.safeSummary exceeds the ${MAX_SAFE_SUMMARY_KEYS} key limit`
+      );
+    }
+    validateBoundedJson(projection.safeSummary, "projection.safeSummary");
+    validateScalarRecord(projection.safeSummary, "projection.safeSummary");
+  }
+  projection.changes.forEach((change, index) => {
+    const changePath = `projection.changes[${index}]`;
+    validateBoundedJson(change, changePath);
+    if (!change || typeof change !== "object" || Array.isArray(change)) {
+      throw new Error(`${changePath} must be an object`);
+    }
+    const rawChange = change;
+    const kind = requireNonEmptyString(rawChange.kind, `${changePath}.kind`);
+    if (kind === "object") {
+      const operation = requireNonEmptyString(
+        rawChange.operation,
+        `${changePath}.operation`
+      );
+      if (operation !== "created" && operation !== "updated" && operation !== "deleted") {
+        throw new Error(
+          `${changePath}.operation must be created, updated, or deleted`
+        );
+      }
+      if (operation === "deleted") {
+        validateObjectReference(rawChange.target, `${changePath}.target`);
+      } else {
+        validateProjectedRecord(rawChange.record, `${changePath}.record`);
+      }
+    } else if (kind === "relationship") {
+      const operation = requireNonEmptyString(
+        rawChange.operation,
+        `${changePath}.operation`
+      );
+      if (operation !== "connected" && operation !== "disconnected") {
+        throw new Error(
+          `${changePath}.operation must be connected or disconnected`
+        );
+      }
+      requireNonEmptyString(
+        rawChange.relationship,
+        `${changePath}.relationship`
+      );
+      validateObjectReference(rawChange.from, `${changePath}.from`);
+      validateObjectReference(rawChange.to, `${changePath}.to`);
+    } else if (kind === "state_observation") {
+      if (rawChange.operation !== void 0) {
+        throw new Error(
+          `${changePath}.operation is not valid for an observation`
+        );
+      }
+      validateObjectReference(rawChange.target, `${changePath}.target`);
+      requireNonEmptyString(rawChange.machine, `${changePath}.machine`);
+      requireNonEmptyString(rawChange.state, `${changePath}.state`);
+    } else {
+      throw new Error(`${changePath}.kind is unsupported: ${kind}`);
+    }
+  });
+  const objectOperations = /* @__PURE__ */ new Map();
+  for (const change of projection.changes) {
+    if (change.kind !== "object") continue;
+    const reference = change.operation === "deleted" ? change.target : change.record;
+    const key = `${reference.className}\0${reference.id}`;
+    const operations = objectOperations.get(key) || {
+      deleted: false,
+      upserted: false
+    };
+    if (change.operation === "deleted") operations.deleted = true;
+    else operations.upserted = true;
+    if (operations.deleted && operations.upserted) {
+      throw new Error(
+        `projection.changes cannot both delete and upsert ${reference.className}/${reference.id}; return only its canonical final state`
+      );
+    }
+    objectOperations.set(key, operations);
+  }
+  const outcome = projection.outcome;
+  if (declaration.kind === "transition") {
+    if (!outcome) {
+      throw new Error("A transition projection must return an outcome");
+    }
+    requireNonEmptyString(outcome.key, "projection.outcome.key");
+    if (outcome.error) {
+      validateBoundedJson(outcome.error, "projection.outcome.error");
+    }
+  } else if (projection.outcome !== void 0) {
+    throw new Error("An effect projection cannot declare a transition outcome");
+  }
+}
+function canonicalizeCommitValue(value) {
+  const normalize = (current) => {
+    if (current === null || typeof current === "boolean" || typeof current === "string") {
+      return typeof current === "string" ? current.normalize("NFC") : current;
+    }
+    if (typeof current === "number") {
+      if (!Number.isFinite(current)) {
+        throw new Error("Cannot canonicalize a non-finite number");
+      }
+      return Object.is(current, -0) ? 0 : current;
+    }
+    if (Array.isArray(current)) return current.map(normalize);
+    if (current && typeof current === "object") {
+      return Object.fromEntries(
+        Object.entries(current).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key.normalize("NFC"), normalize(item)])
+      );
+    }
+    throw new Error(`Cannot canonicalize ${typeof current}`);
+  };
+  return JSON.stringify(normalize(value));
+}
+
 // src/effect-runtime.ts
 function computeEffectKey(effect) {
   const attachedClass = effect.className?.trim();
@@ -23700,6 +23981,45 @@ function resolveInvocationMode(context) {
   }
   return "execute";
 }
+async function sha256Hex(value) {
+  const digest = await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(value)
+  );
+  return Array.from(
+    new Uint8Array(digest),
+    (byte) => byte.toString(16).padStart(2, "0")
+  ).join("");
+}
+async function resolveInvocationIdempotencyKey(request) {
+  const supplied = request.context?.idempotencyKey?.trim();
+  if (supplied) return supplied;
+  const invocationId = request.context?.invocationId?.trim();
+  if (!invocationId) {
+    throw new Error(
+      `Committed effect ${request.effectKey} requires an invocation id`
+    );
+  }
+  const digest = await sha256Hex(
+    canonicalizeCommitValue({
+      sandboxId: request.context?.sandboxId || "",
+      environmentId: request.context?.environmentId || "",
+      effectKey: request.effectKey,
+      invocationId,
+      input: request.input
+    })
+  );
+  return `gci_${digest}`;
+}
+function createUnavailableCommitContext(message) {
+  const unavailable = async () => {
+    throw new Error(message);
+  };
+  return {
+    effect: unavailable,
+    transition: unavailable
+  };
+}
 function resolveReverseEffect(effectMap, currentEffect, request, behaviors) {
   const explicitReverseHandler = request.context?.invocation?.reverseHandler?.trim();
   const configuredReverseHandler = behaviors.reverse?.handler?.trim();
@@ -23771,22 +24091,32 @@ function resolveHandlerForMode(effectMap, effect, request) {
     throw new Error(`Dry run is not supported for ${request.effectKey}`);
   }
   if (mode === "reverse") {
+    const sourceEffectKey = request.context?.invocation?.sourceEffectKey?.trim();
+    if (sourceEffectKey && sourceEffectKey !== request.effectKey) {
+      return { effect, mode, handler: effect.handler };
+    }
+    const namedReverseHandler = request.context?.invocation?.reverseHandler?.trim() || behaviors.reverse?.handler?.trim();
+    if (namedReverseHandler) {
+      const reverseEffect = resolveReverseEffect(
+        effectMap,
+        effect,
+        request,
+        behaviors
+      );
+      if (reverseEffect) {
+        return {
+          effect: reverseEffect,
+          mode,
+          handler: reverseEffect.handler
+        };
+      }
+      throw new Error(
+        `Reverse effect ${namedReverseHandler} is not registered for ${request.effectKey}`
+      );
+    }
     if (effect.reverseHandler) {
       return { effect, mode, handler: effect.reverseHandler };
     }
-    const reverseEffect = resolveReverseEffect(
-      effectMap,
-      effect,
-      request,
-      behaviors
-    );
-    if (reverseEffect) {
-      return {
-        effect: reverseEffect,
-        mode,
-        handler: reverseEffect.reverseHandler || reverseEffect.handler
-      };
-    }
     throw new Error(
       `Reverse execution is not supported for ${request.effectKey}`
     );
@@ -23887,18 +24217,142 @@ async function invokeRegisteredEffect(effectMap, request, options = {}) {
     throw new Error(`Effect handler not found: ${request.effectKey}`);
   }
   const resolved = resolveHandlerForMode(effectMap, effect, request);
+  const isPreResolvedNamedReverse = resolved.mode === "reverse" && Boolean(request.context?.invocation?.sourceEffectKey?.trim()) && request.context?.invocation?.sourceEffectKey?.trim() !== request.effectKey;
+  const resolvedEffectKey = computeEffectKey(resolved.effect);
+  if (resolved.mode === "reverse" && resolved.effect !== effect && (effect.commit || resolved.effect.commit)) {
+    throw new Error(
+      `Committed named reverse effect ${resolvedEffectKey} must be reserved and dispatched using its own effect key; customer code was not invoked`
+    );
+  }
+  const declaration = resolved.effect.commit;
+  const commitTransport = options.commit;
+  const commitRequired = Boolean(declaration) && (resolved.mode === "execute" || resolved.mode === "reverse");
+  if (commitRequired && !commitTransport) {
+    throw new Error(
+      `Committed effect ${request.effectKey} has no durable commit transport; customer code was not invoked`
+    );
+  }
+  if (commitRequired && declaration?.kind === "transition" && !request.context?.invocation?.transition) {
+    throw new Error(
+      `Transition effect ${request.effectKey} has no resolved transition context; customer code was not invoked`
+    );
+  }
+  const idempotencyKey = commitRequired ? await resolveInvocationIdempotencyKey(request) : request.context?.idempotencyKey;
+  let commitStarted = false;
+  let commitPromise = null;
+  const beginCommit = (requestedKind, productResult) => {
+    if (!declaration || !commitRequired || !commitTransport) {
+      return Promise.reject(
+        new Error(
+          `Effect ${request.effectKey} does not declare an active ${requestedKind} commit`
+        )
+      );
+    }
+    if (declaration.kind !== requestedKind) {
+      return Promise.reject(
+        new Error(
+          `Effect ${request.effectKey} declares ${declaration.kind} commit, not ${requestedKind}`
+        )
+      );
+    }
+    if (commitStarted) {
+      return Promise.reject(
+        new Error(
+          `Effect invocation ${request.context?.invocationId || request.effectKey} already emitted its commit`
+        )
+      );
+    }
+    commitStarted = true;
+    commitPromise = (async () => {
+      let projection;
+      try {
+        projection = declaration.project(productResult);
+        validateProjectionResult(declaration, projection);
+      } catch (error2) {
+        const message = error2 instanceof Error ? error2.message : String(error2);
+        if (commitTransport.mappingFailed) {
+          await commitTransport.mappingFailed({
+            effectKey: request.effectKey,
+            effectName: request.effectName,
+            invocationId: request.context?.invocationId || "",
+            idempotencyKey: idempotencyKey || "",
+            environmentId: request.context?.environmentId || "",
+            message
+          });
+        }
+        throw new Error(
+          `Product mutation may have succeeded, but its commit projection is invalid: ${message}`
+        );
+      }
+      if (requestedKind === "transition") {
+        const transition = request.context?.invocation?.transition;
+        const outcome = projection.outcome;
+        if (!transition || !outcome?.key) {
+          throw new Error(
+            `Transition effect ${request.effectKey} did not resolve an authored outcome`
+          );
+        }
+        if (!Object.prototype.hasOwnProperty.call(
+          transition.outcomes,
+          outcome.key
+        )) {
+          throw new Error(
+            `Transition ${transition.machine}.${transition.transition} does not declare outcome ${outcome.key}`
+          );
+        }
+      }
+      const invocationId = request.context?.invocationId || "";
+      const environmentId = request.context?.environmentId || "";
+      const sandboxId = request.context?.sandboxId || "";
+      if (!invocationId || !environmentId || !sandboxId || !idempotencyKey) {
+        throw new Error(
+          `Committed effect ${request.effectKey} is missing its trusted invocation scope`
+        );
+      }
+      const commitRequest = {
+        kind: requestedKind,
+        effectKey: request.effectKey,
+        effectName: request.effectName,
+        operationLabel: resolved.effect.label || resolved.effect.name,
+        invocationId,
+        idempotencyKey,
+        sandboxId,
+        environmentId,
+        ...request.context?.sessionId ? { sessionId: request.context.sessionId } : {},
+        ...request.context?.jobId ? { jobId: request.context.jobId } : {},
+        ...request.context?.buildId ? { buildId: request.context.buildId } : {},
+        ...request.context?.invocation?.artifactId ? { artifactId: request.context.invocation.artifactId } : {},
+        projection,
+        ...requestedKind === "transition" && request.context?.invocation?.transition ? { transition: request.context.invocation.transition } : {}
+      };
+      const receipt = await commitTransport.persist(commitRequest);
+      await options.commitAcknowledged?.(receipt);
+      return receipt;
+    })();
+    return commitPromise;
+  };
+  const commitContext = commitRequired ? {
+    effect: (productResult) => beginCommit("effect", productResult),
+    transition: (productResult) => beginCommit("transition", productResult)
+  } : createUnavailableCommitContext(
+    `Effect ${request.effectKey} is not executing a declared product commit`
+  );
   const context = {
     ...request.context || {},
+    ...idempotencyKey ? { idempotencyKey } : {},
+    commit: commitContext,
     behaviors: normalizeEffectBehaviors(
       request.context?.behaviors || effect.metamodels || void 0
     ),
     invocation: {
       mode: resolved.mode,
-      sourceEffectKey: request.effectKey,
-      sourceEffectName: request.effectName,
+      ...commitRequired && declaration ? { commitKind: declaration.kind } : {},
+      sourceEffectKey: isPreResolvedNamedReverse ? request.context?.invocation?.sourceEffectKey || request.effectKey : request.effectKey,
+      sourceEffectName: isPreResolvedNamedReverse ? request.context?.invocation?.sourceEffectName || request.effectName : request.effectName,
       ...request.context?.invocation?.reverseHandler ? { reverseHandler: request.context.invocation.reverseHandler } : {},
       ...request.context?.invocation?.artifactId ? { artifactId: request.context.invocation.artifactId } : {},
-      ...request.context?.invocation?.artifactOptions ? { artifactOptions: request.context.invocation.artifactOptions } : {}
+      ...request.context?.invocation?.artifactOptions ? { artifactOptions: request.context.invocation.artifactOptions } : {},
+      ...request.context?.invocation?.transition ? { transition: request.context.invocation.transition } : {}
     }
   };
   const feedbackContext = options.feedback ? createInvocationFeedbackContext(options.feedback) : null;
@@ -23922,6 +24376,16 @@ async function invokeRegisteredEffect(effectMap, request, options = {}) {
     handlerFailed = true;
     handlerError = error2;
   }
+  let commitError;
+  let commitFailed = false;
+  if (commitPromise) {
+    try {
+      await commitPromise;
+    } catch (error2) {
+      commitFailed = true;
+      commitError = error2;
+    }
+  }
   let feedbackError;
   let feedbackFailed = false;
   if (feedbackContext) {
@@ -23935,9 +24399,17 @@ async function invokeRegisteredEffect(effectMap, request, options = {}) {
   if (handlerFailed) {
     throw handlerError;
   }
+  if (commitFailed) {
+    throw commitError;
+  }
   if (feedbackFailed) {
     throw feedbackError;
   }
+  if (commitRequired && !commitStarted) {
+    throw new Error(
+      `Mutating effect ${request.effectKey} returned without acknowledging its product mutation`
+    );
+  }
   return handlerResult;
 }
 
@@ -24006,12 +24478,7 @@ function toRecordSearchResult(className, node) {
     (field) => normalizeGraphPathSegment(field.name) === "real_id" && typeof field.value === "string" && field.value.trim()
   );
   const id = typeof realIdField?.value === "string" ? realIdField.value.trim() : graphPathId;
-  const rawLabel = typeof node.label === "string" && node.label.trim() ? node.label : "";
-  if (fields.length === 0 && rawLabel && isPlaceholderRecordLabel(rawLabel, graphPathId, path7)) {
-    return null;
-  }
-  const fallbackLabel = displayLabelFromFields(fields);
-  const label = rawLabel && !isPlaceholderRecordLabel(rawLabel, id, path7) ? rawLabel : fallbackLabel || rawLabel || id;
+  const label = typeof node.label === "string" && node.label.trim() ? node.label.trim() : path7 || id;
   return {
     path: path7,
     className,
@@ -24021,30 +24488,6 @@ function toRecordSearchResult(className, node) {
     fields
   };
 }
-function isPlaceholderRecordLabel(label, id, path7) {
-  const normalizedLabel = normalizeGraphPathSegment(label);
-  return normalizedLabel === normalizeGraphPathSegment(id) || normalizedLabel === normalizeGraphPathSegment(path7);
-}
-function displayLabelFromFields(fields) {
-  const preferredFieldNames = [
-    "name",
-    "title",
-    "label",
-    "display_name",
-    "file_name",
-    "number",
-    "code"
-  ];
-  for (const preferred of preferredFieldNames) {
-    const match = fields.find(
-      (field) => normalizeGraphPathSegment(field.name) === preferred && typeof field.value === "string" && field.value.trim()
-    );
-    if (typeof match?.value === "string") {
-      return match.value.trim();
-    }
-  }
-  return null;
-}
 function normalizeRecordSearchText(value) {
   return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, " ").replace(/\s+/g, " ").trim();
 }
@@ -24674,6 +25117,133 @@ var Environment = class _Environment {
       getAwaitingCount: async () => this.getAwaitingRecordCount()
     };
   }
+  /**
+   * Acknowledge a declared product mutation that already happened outside a
+   * Granular-run effect (for example, in a webhook consumer). These methods
+   * run the declaration's pure projection mapper; they never call its handler.
+   */
+  get commit() {
+    return {
+      effect: async (effect, productResult, options = {}) => this.persistExternalEffect(effect, productResult, options),
+      transition: async (transition, productResult, options = {}) => this.persistExternalTransition(transition, productResult, options),
+      get: async (commitId) => this.controlPlaneRequest(
+        `/control/environments/${this.environmentId}/commits/${encodeURIComponent(
+          commitId
+        )}`
+      ),
+      retry: async (commitId) => this.controlPlaneRequest(
+        `/control/environments/${this.environmentId}/commits/${encodeURIComponent(
+          commitId
+        )}/retry`,
+        { method: "POST" }
+      )
+    };
+  }
+  /** Inspect or retry the agent synchronization of a product snapshot. */
+  get observation() {
+    return {
+      get: async (observationId) => this.controlPlaneRequest(
+        `/control/environments/${this.environmentId}/observations/${encodeURIComponent(
+          observationId
+        )}`
+      ),
+      retry: async (observationId) => this.controlPlaneRequest(
+        `/control/environments/${this.environmentId}/observations/${encodeURIComponent(
+          observationId
+        )}/retry`,
+        { method: "POST" }
+      )
+    };
+  }
+  async persistExternalEffect(effect, productResult, options) {
+    const projection = effect.commit.project(productResult);
+    validateProjectionResult(effect.commit, projection);
+    this.requireExternalIdentity(projection.source.version, options);
+    return this.controlPlaneRequest(
+      `/control/environments/${this.environmentId}/external-commits`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          kind: "effect",
+          effectKey: computeEffectKey2(effect),
+          ...options.sourceEventId?.trim() ? { sourceEventId: options.sourceEventId.trim() } : {},
+          projection
+        })
+      }
+    );
+  }
+  async persistExternalTransition(transition, productResult, options) {
+    const metadata = getDefinedTransitionMetadata(transition);
+    if (!metadata) {
+      throw new Error(
+        "environment.commit.transition requires a transition returned by defineStateMachine"
+      );
+    }
+    const projection = transition.effect.commit.project(productResult);
+    validateProjectionResult(transition.effect.commit, projection);
+    this.requireExternalIdentity(projection.source.version, options);
+    if (!Object.prototype.hasOwnProperty.call(
+      transition.outcomes,
+      projection.outcome.key
+    )) {
+      throw new Error(
+        `Transition ${metadata.machine}.${metadata.transition} does not declare outcome ${projection.outcome.key}`
+      );
+    }
+    if (!projection.primaryTarget) {
+      throw new Error(
+        "An external transition projection requires primaryTarget to identify the transitioned product record"
+      );
+    }
+    return this.controlPlaneRequest(
+      `/control/environments/${this.environmentId}/external-commits`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          kind: "transition",
+          effectKey: computeEffectKey2(transition.effect),
+          ...options.sourceEventId?.trim() ? { sourceEventId: options.sourceEventId.trim() } : {},
+          projection,
+          transition: {
+            className: projection.primaryTarget.className,
+            objectId: projection.primaryTarget.id,
+            ...projection.primaryTarget.path ? { objectPath: projection.primaryTarget.path } : {},
+            machine: metadata.machine,
+            transition: metadata.transition,
+            from: transition.from
+          }
+        })
+      }
+    );
+  }
+  requireExternalIdentity(sourceVersion, options) {
+    if (!options.sourceEventId?.trim() && !sourceVersion?.trim()) {
+      throw new Error(
+        "An external commit requires sourceEventId or a source version from its projection mapper"
+      );
+    }
+  }
+  /**
+   * Synchronize a versioned product snapshot without claiming an effect or
+   * lifecycle transition. This records no transition history.
+   */
+  async observe(mapper, productResult) {
+    const declaration = { kind: "effect"};
+    const projection = mapper(productResult);
+    validateProjectionResult(declaration, projection);
+    if (!projection.source.version?.trim()) {
+      throw new Error(
+        "environment.observe requires a monotonic source version or serialized adapter sequence"
+      );
+    }
+    return this.controlPlaneRequest(
+      `/control/environments/${this.environmentId}/observations`,
+      {
+        method: "POST",
+        body: JSON.stringify({ projection })
+      }
+    );
+  }
   /**
    * Mirror product-owned workflow state into Granular without making Granular
    * own the customer application's state machine.
@@ -26080,6 +26650,14 @@ var EnvironmentSession = class extends Session {
       }
     };
   }
+  get mutations() {
+    return {
+      list: (options = {}) => this.sessionDataRequest(
+        "/mutations",
+        options
+      )
+    };
+  }
   get artifacts() {
     return {
       list: (options = {}) => {
@@ -27579,6 +28157,7 @@ var Granular = class _Granular {
     const serialized = {
       effectKey: computeEffectKey2(effect),
       name: effect.name,
+      ...effect.label ? { label: effect.label } : {},
       description: effect.description,
       inputSchema: effect.inputSchema,
       stability: effect.stability || "stable",
@@ -27602,6 +28181,9 @@ var Granular = class _Granular {
     if (effect.metamodels !== void 0) {
       serialized.metamodels = effect.metamodels;
     }
+    if (effect.commit !== void 0) {
+      serialized.commit = { kind: effect.commit.kind };
+    }
     return serialized;
   }
   async publishSandboxEffectCatalog(host) {
@@ -27822,16 +28404,60 @@ var Granular = class _Granular {
       };
       wsClient.registerRpcHandler("effect.invoke", async (params) => {
         const request = params;
-        return invokeRegisteredEffect(
+        let commitReceipt;
+        const result = await invokeRegisteredEffect(
           this.getSandboxEffectMap(sandboxId),
           request,
           {
+            commitAcknowledged: (receipt) => {
+              commitReceipt = receipt;
+            },
+            commit: {
+              persist: (commitRequest) => this.request(
+                `/control/environments/${encodeURIComponent(
+                  commitRequest.environmentId
+                )}/commits`,
+                {
+                  method: "POST",
+                  body: JSON.stringify({
+                    kind: commitRequest.kind,
+                    invocationId: commitRequest.invocationId,
+                    idempotencyKey: commitRequest.idempotencyKey,
+                    effectKey: commitRequest.effectKey,
+                    projection: commitRequest.projection
+                  })
+                }
+              ),
+              mappingFailed: (failure) => this.request(
+                `/control/environments/${encodeURIComponent(
+                  failure.environmentId
+                )}/commit-invocations/${encodeURIComponent(
+                  failure.invocationId
+                )}`,
+                {
+                  method: "PATCH",
+                  body: JSON.stringify({
+                    status: "mapping_failed",
+                    error: {
+                      code: "commit_projection_mapping_failed",
+                      message: failure.message,
+                      retryable: false
+                    }
+                  })
+                }
+              )
+            },
             feedback: {
               invocationId: request.callId,
               publish: (method, publishParams) => wsClient.call(method, publishParams)
             }
           }
         );
+        return {
+          __granularEffectInvocationResult: true,
+          result,
+          ...commitReceipt ? { commit: commitReceipt } : {}
+        };
       });
       wsClient.on("open", () => {
         void this.synchronizeEffectHost(host).catch((error2) => {