@granular-software/sdk 0.4.63 → 0.4.65

package/dist/index.js

@@ -6555,6 +6555,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 || "",
@@ -6567,6 +6572,10 @@ var Session = class {
         userId: "",
         subjectId: ""
       },
+      commit: {
+        effect: commitUnavailable,
+        transition: commitUnavailable
+      },
       ...feedbackContext ? {
         feedback: feedbackContext.feedback,
         transientFeedback: feedbackContext.transientFeedback
@@ -12219,8 +12228,12 @@ external_exports.union([
   external_exports.array(external_exports.string()),
   external_exports.object({
     values: external_exports.array(external_exports.string()),
+    labels: external_exports.array(external_exports.string().min(1)).optional(),
     message: external_exports.string().optional()
-  }).strict()
+  }).strict().refine(
+    (rule) => !rule.labels || rule.labels.length === rule.values.length,
+    { message: "Enum labels must match enum values one-for-one" }
+  )
 ]);
 external_exports.union([
   external_exports.boolean(),
@@ -12248,7 +12261,7 @@ var StateMachineStateSchema = external_exports.union([
   external_exports.string(),
   external_exports.object({
     name: external_exports.string().min(1),
-    label: external_exports.string().optional(),
+    label: external_exports.string().min(1).optional(),
     description: external_exports.string().optional(),
     isFinal: external_exports.boolean().optional()
   }).strict()
@@ -12334,6 +12347,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),
@@ -12345,7 +12364,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),
@@ -13026,6 +13046,289 @@ var effectBehaviorsMetamodelPackage = defineMetamodelPackage({
   }
 });
 
+// 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 defineProjection(mapper) {
+  return mapper;
+}
+function defineEffect(effect) {
+  return effect;
+}
+function defineStateMachine(definition) {
+  const stateNames = new Set(Object.keys(definition.states));
+  for (const [transitionName, transition] of Object.entries(
+    definition.transitions
+  )) {
+    if (!stateNames.has(transition.from)) {
+      throw new Error(
+        `Transition ${transitionName} starts at undeclared state ${transition.from}`
+      );
+    }
+    if (transition.effect.commit?.kind !== "transition") {
+      throw new Error(
+        `Transition ${transitionName} must use a transition-commit effect`
+      );
+    }
+    const outcomes = Object.entries(transition.outcomes);
+    const primary = outcomes.filter(([, outcome]) => outcome.primary === true);
+    if (primary.length !== 1) {
+      throw new Error(
+        `Transition ${transitionName} must declare exactly one primary outcome`
+      );
+    }
+    for (const [outcomeKey, outcome] of outcomes) {
+      if (outcome.to !== "$current" && !stateNames.has(outcome.to)) {
+        throw new Error(
+          `Transition ${transitionName} outcome ${outcomeKey} targets undeclared state ${outcome.to}`
+        );
+      }
+      if (outcome.to === "$current" && outcome.disposition !== "error") {
+        throw new Error(
+          `Transition ${transitionName} outcome ${outcomeKey} may use $current only with error disposition`
+        );
+      }
+    }
+  }
+  for (const [transitionName, transition] of Object.entries(
+    definition.transitions
+  )) {
+    definedTransitionMetadata.set(transition, {
+      machine: definition.name,
+      transition: transitionName
+    });
+  }
+  return definition;
+}
+function requireNonEmptyString(value, path) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${path} must be a non-empty string`);
+  }
+  return value.trim();
+}
+function validateObjectReference(value, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${path} must be an object reference`);
+  }
+  const reference = value;
+  requireNonEmptyString(reference.className, `${path}.className`);
+  requireNonEmptyString(reference.id, `${path}.id`);
+  if (reference.path !== void 0) {
+    requireNonEmptyString(reference.path, `${path}.path`);
+  }
+}
+function validateScalarRecord(value, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value) || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new Error(`${path} 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(
+        `${path}.${key} must be a string, finite number, boolean, or null`
+      );
+    }
+    if (typeof item === "number" && !Number.isFinite(item)) {
+      throw new Error(`${path}.${key} must be finite`);
+    }
+  }
+}
+function validateProjectedRecord(value, path) {
+  validateObjectReference(value, path);
+  const record = value;
+  if (record.label !== void 0) {
+    if (typeof record.label !== "string") {
+      throw new Error(`${path}.label must be a string`);
+    }
+    if (record.label.length > MAX_SAFE_TEXT_LENGTH) {
+      throw new Error(
+        `${path}.label exceeds ${MAX_SAFE_TEXT_LENGTH} characters`
+      );
+    }
+  }
+  validateScalarRecord(record.fields, `${path}.fields`);
+}
+function validateBoundedJson(value, path, depth = 0) {
+  if (depth > 12) throw new Error(`${path} is nested too deeply`);
+  if (value === null || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`${path} must be finite`);
+    return;
+  }
+  if (typeof value === "string") {
+    if (value.length > MAX_SAFE_TEXT_LENGTH) {
+      throw new Error(`${path} exceeds ${MAX_SAFE_TEXT_LENGTH} characters`);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > MAX_PROJECTION_CHANGES) {
+      throw new Error(`${path} contains too many values`);
+    }
+    value.forEach(
+      (item, index) => validateBoundedJson(item, `${path}[${index}]`, depth + 1)
+    );
+    return;
+  }
+  if (!value || typeof value !== "object") {
+    throw new Error(`${path} contains an unsupported value`);
+  }
+  const entries = Object.entries(value);
+  if (entries.length > 256) throw new Error(`${path} contains too many keys`);
+  for (const [key, item] of entries) {
+    if (/token|secret|password|authorization|cookie/i.test(key)) {
+      throw new Error(`${path}.${key} is not allowed in a commit projection`);
+    }
+    validateBoundedJson(item, `${path}.${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();
@@ -13090,6 +13393,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();
@@ -13142,7 +13484,7 @@ function resolveHandlerForMode(effectMap, effect, request) {
   if (mode === "artifactOptions") {
     if (!effect.artifactOptionsHandler) {
       throw new Error(
-        `Artifact relationship options are not supported for ${request.effectKey}`
+        `Artifact field options are not supported for ${request.effectKey}`
       );
     }
     return {
@@ -13161,22 +13503,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}`
     );
@@ -13277,18 +13629,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 (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        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;
@@ -13312,6 +13788,16 @@ async function invokeRegisteredEffect(effectMap, request, options = {}) {
     handlerFailed = true;
     handlerError = error;
   }
+  let commitError;
+  let commitFailed = false;
+  if (commitPromise) {
+    try {
+      await commitPromise;
+    } catch (error) {
+      commitFailed = true;
+      commitError = error;
+    }
+  }
   let feedbackError;
   let feedbackFailed = false;
   if (feedbackContext) {
@@ -13325,9 +13811,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;
 }
 
@@ -13396,12 +13890,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, path)) {
-    return null;
-  }
-  const fallbackLabel = displayLabelFromFields(fields);
-  const label = rawLabel && !isPlaceholderRecordLabel(rawLabel, id, path) ? rawLabel : fallbackLabel || rawLabel || id;
+  const label = typeof node.label === "string" && node.label.trim() ? node.label.trim() : path || id;
   return {
     path,
     className,
@@ -13411,30 +13900,6 @@ function toRecordSearchResult(className, node) {
     fields
   };
 }
-function isPlaceholderRecordLabel(label, id, path) {
-  const normalizedLabel = normalizeGraphPathSegment(label);
-  return normalizedLabel === normalizeGraphPathSegment(id) || normalizedLabel === normalizeGraphPathSegment(path);
-}
-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();
 }
@@ -13644,18 +14109,24 @@ function normalizeEnumInput(enumSpec) {
     (value) => typeof value === "string" && value.length > 0
   );
   if (values.length === 0) return null;
-  return config.message ? { values, message: config.message } : { values };
+  const labels = Array.isArray(config.labels) && config.labels.length === values.length ? config.labels : values;
+  return {
+    values,
+    labels,
+    ...config.message ? { message: config.message } : {}
+  };
 }
 function buildEnumFieldMutations(fieldPath, enumSpec) {
   const normalized = normalizeEnumInput(enumSpec);
   if (!normalized) return [];
   const messageArg = normalized.message ? `, message: ${JSON.stringify(normalized.message)}` : "";
+  const labelsArg = normalized.labels ? `, labels: ${JSON.stringify(normalized.labels)}` : "";
   return [
     {
       label: `set enum on ${fieldPath}`,
       query: `mutation { at(path: ${JSON.stringify(fieldPath)}) { set_enum(values: ${JSON.stringify(
         normalized.values
-      )}${messageArg}) { values } } }`
+      )}${labelsArg}${messageArg}) { values labels } } }`
     }
   ];
 }
@@ -13665,7 +14136,7 @@ var enumMetamodelPackage = defineMetamodelPackage({
     fieldRows: [
       {
         key: "enum",
-        description: 'Allowed values. Accepts `["a", "b"]` or `{ "values": [...], "message": "..." }`.'
+        description: 'Allowed values. Use `{ "values": [...], "labels": [...] }` for authored display labels; otherwise each unchanged value is its display fallback.'
       }
     ]
   },
@@ -13675,6 +14146,7 @@ var enumMetamodelPackage = defineMetamodelPackage({
       type EnumMetamodel {
         model: Model!
         values: [String!]!
+        labels: [String!]!
         message: String
       }
 
@@ -13683,7 +14155,7 @@ var enumMetamodelPackage = defineMetamodelPackage({
       }
 
       extend type ModelMutation {
-        set_enum(values: [String!]!, message: String): EnumMetamodel
+        set_enum(values: [String!]!, labels: [String!], message: String): EnumMetamodel
       }
       `
     ],
@@ -13692,15 +14164,19 @@ var enumMetamodelPackage = defineMetamodelPackage({
         EnumMetamodel: {
           model: (value) => value.model,
           values: (value) => value.values,
+          labels: (value) => value.labels || [],
           message: (value) => value.message || null
         },
         Model: {
           enum_rule: async (ant) => await run(ant.enum_rule())
         },
         ModelMutation: {
-          set_enum: async (ant, { values, message }) => {
-            const model = await run(ant.set_enum(values, message));
-            return { model, values, message };
+          set_enum: async (ant, { values, labels, message }) => {
+            const resolvedLabels = Array.isArray(labels) && labels.length === values.length ? labels : values;
+            const model = await run(
+              ant.set_enum(values, resolvedLabels, message)
+            );
+            return { model, values, labels: resolvedLabels, message };
           }
         }
       };
@@ -13713,7 +14189,7 @@ var enumMetamodelPackage = defineMetamodelPackage({
   },
   summary: {
     selections: {
-      propertyFields: [`enum_rule { values message }`]
+      propertyFields: [`enum_rule { values labels message }`]
     },
     readPropertySummary(rawProperty) {
       const values = Array.isArray(rawProperty.enum_rule?.values) ? rawProperty.enum_rule.values.filter(
@@ -13721,8 +14197,15 @@ var enumMetamodelPackage = defineMetamodelPackage({
       ) : [];
       if (values.length === 0) return { enumRule: null };
       const message = typeof rawProperty.enum_rule?.message === "string" ? rawProperty.enum_rule.message : null;
+      const labels = Array.isArray(rawProperty.enum_rule?.labels) ? rawProperty.enum_rule.labels.filter(
+        (label) => typeof label === "string" && label.length > 0
+      ) : [];
       return {
-        enumRule: message ? { values, message } : { values }
+        enumRule: {
+          values,
+          ...labels.length === values.length ? { labels } : {},
+          ...message ? { message } : {}
+        }
       };
     }
   },
@@ -14379,7 +14862,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
     );
@@ -14472,6 +14956,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) {
@@ -14534,7 +15023,7 @@ function buildMachineTypes(classSummary, machine) {
   ];
 }
 function buildMachineMethods(classSummary, machine) {
-  const stateName = stateTypeName(classSummary.name, machine.name);
+  const stateName2 = stateTypeName(classSummary.name, machine.name);
   const transitionName = transitionTypeName(classSummary.name, machine.name);
   pathTypeName(classSummary.name, machine.name);
   const docsPrefix = `${classSummary.name}.${machine.name}`;
@@ -14544,12 +15033,12 @@ function buildMachineMethods(classSummary, machine) {
       docs: [`Get the current ${docsPrefix} state.`],
       static: false,
       params: [],
-      returnType: `Promise<${stateName} | null>`,
+      returnType: `Promise<${stateName2} | null>`,
       runtime: {
         kind: "state_machine",
         machineName: machine.name,
         className: classSummary.name,
-        stateTypeName: stateName,
+        stateTypeName: stateName2,
         transitionTypeName: transitionName,
         operation: "get_current"
       }
@@ -14560,13 +15049,13 @@ function buildMachineMethods(classSummary, machine) {
         `Reach a ${docsPrefix} state through the shortest allowed transition path.`
       ],
       static: false,
-      params: [{ name: "target", type: stateName }],
+      params: [{ name: "target", type: stateName2 }],
       returnType: `Promise<${toPascalCase2(classSummary.name)}>`,
       runtime: {
         kind: "state_machine",
         machineName: machine.name,
         className: classSummary.name,
-        stateTypeName: stateName,
+        stateTypeName: stateName2,
         transitionTypeName: transitionName,
         operation: "reach"
       }
@@ -14581,7 +15070,7 @@ function buildMachineMethods(classSummary, machine) {
         kind: "state_machine",
         machineName: machine.name,
         className: classSummary.name,
-        stateTypeName: stateName,
+        stateTypeName: stateName2,
         transitionTypeName: transitionName,
         operation: "list_transitions"
       }
@@ -14591,12 +15080,12 @@ function buildMachineMethods(classSummary, machine) {
       docs: [`List reachable states for ${docsPrefix} from the current state.`],
       static: false,
       params: [],
-      returnType: `Promise<${stateName}[]>`,
+      returnType: `Promise<${stateName2}[]>`,
       runtime: {
         kind: "state_machine",
         machineName: machine.name,
         className: classSummary.name,
-        stateTypeName: stateName,
+        stateTypeName: stateName2,
         transitionTypeName: transitionName,
         operation: "list_reachable_states"
       }
@@ -14611,7 +15100,7 @@ function buildMachineMethods(classSummary, machine) {
         kind: "state_machine",
         machineName: machine.name,
         className: classSummary.name,
-        stateTypeName: stateName,
+        stateTypeName: stateName2,
         transitionTypeName: transitionName,
         operation: "is_final"
       }
@@ -14622,13 +15111,13 @@ function buildMachineMethods(classSummary, machine) {
         `List shortest transition paths from the current ${docsPrefix} state to a target state.`
       ],
       static: false,
-      params: [{ name: "target", type: stateName }],
-      returnType: `Promise<Array<{ states: ${stateName}[]; transitions: ${transitionName}[] }>>`,
+      params: [{ name: "target", type: stateName2 }],
+      returnType: `Promise<Array<{ states: ${stateName2}[]; transitions: ${transitionName}[] }>>`,
       runtime: {
         kind: "state_machine",
         machineName: machine.name,
         className: classSummary.name,
-        stateTypeName: stateName,
+        stateTypeName: stateName2,
         transitionTypeName: transitionName,
         operation: "paths_to"
       }
@@ -14652,7 +15141,7 @@ function buildMachineMethods(classSummary, machine) {
           kind: "state_machine",
           machineName: machine.name,
           className: classSummary.name,
-          stateTypeName: stateName,
+          stateTypeName: stateName2,
           transitionTypeName: transitionName,
           operation: "reach",
           targetState: stateNameValue,
@@ -14671,7 +15160,7 @@ function buildMachineMethods(classSummary, machine) {
           kind: "state_machine",
           machineName: machine.name,
           className: classSummary.name,
-          stateTypeName: stateName,
+          stateTypeName: stateName2,
           transitionTypeName: transitionName,
           operation: "prepare_reach",
           targetState: stateNameValue,
@@ -14684,7 +15173,7 @@ function buildMachineMethods(classSummary, machine) {
         kind: "state_machine",
         machineName: machine.name,
         className: classSummary.name,
-        stateTypeName: stateName,
+        stateTypeName: stateName2,
         transitionTypeName: transitionName,
         operation: "prepare_create_reach",
         targetState: stateNameValue,
@@ -14750,7 +15239,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!
       }
 
@@ -14767,6 +15256,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!
       }
 
@@ -14813,6 +15303,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
         permission_json: String
         risk: String
         expected_outcome_json: String
+        outcomes_json: String
       }
 
       type StateMachinePath {
@@ -14823,6 +15314,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!
@@ -14888,7 +15383,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(
@@ -14904,7 +15400,8 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
                   requirementsJson: requirements_json,
                   permissionJson: permission_json,
                   risk,
-                  expectedOutcomeJson: expected_outcome_json
+                  expectedOutcomeJson: expected_outcome_json,
+                  outcomesJson: outcomes_json
                 }
               )
             );
@@ -14925,6 +15422,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(
@@ -14954,7 +15464,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,
@@ -14963,6 +15474,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
@@ -15036,6 +15551,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
             permission_json
             risk
             expected_outcome_json
+            outcomes_json
           }
         }`
       ]
@@ -15763,6 +16279,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.
@@ -15802,8 +16445,8 @@ var Environment = class _Environment {
    * `await env.recordState({ className: "spend_request", id, machine: "lifecycle", state: "policy_review", source: "customer_backend" })`
    */
   state(target) {
-    const observe = async (machineName, stateName, input = {}) => {
-      const observedState = input.observedState || input.state || stateName;
+    const observe = async (machineName, stateName2, input = {}) => {
+      const observedState = input.observedState || input.state || stateName2;
       if (!observedState) {
         throw new Error("State observation requires a target state");
       }
@@ -15829,7 +16472,7 @@ var Environment = class _Environment {
             {
               get: (_machineTarget, stateProperty) => {
                 if (stateProperty === "to") {
-                  return (stateName, input) => observe(machineProperty, stateName, input || {});
+                  return (stateName2, input) => observe(machineProperty, stateName2, input || {});
                 }
                 if (typeof stateProperty !== "string") return void 0;
                 return (input) => observe(
@@ -17169,6 +17812,14 @@ var EnvironmentSession = class extends Session {
       }
     };
   }
+  get mutations() {
+    return {
+      list: (options = {}) => this.sessionDataRequest(
+        "/mutations",
+        options
+      )
+    };
+  }
   get artifacts() {
     return {
       list: (options = {}) => {
@@ -18668,6 +19319,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",
@@ -18691,6 +19343,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) {
@@ -18911,16 +19566,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((error) => {
@@ -19492,6 +20191,275 @@ var Granular = class _Granular {
   }
 };
 
+// src/record-snapshot-projection.ts
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, stableValue(item)])
+    );
+  }
+  return value;
+}
+function stableJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+function recordKey(record) {
+  return `${record.className}\0${record.id}`;
+}
+function recordReference(className, id) {
+  return { className, id };
+}
+function changedRecordSnapshots(beforeRecords, afterRecords) {
+  const before = new Map(
+    beforeRecords.map((record) => [recordKey(record), record])
+  );
+  const after = new Map(
+    afterRecords.map((record) => [recordKey(record), record])
+  );
+  const changedKeys = /* @__PURE__ */ new Set();
+  for (const key of /* @__PURE__ */ new Set([...before.keys(), ...after.keys()])) {
+    if (stableJson(before.get(key)) !== stableJson(after.get(key))) {
+      changedKeys.add(key);
+    }
+  }
+  return {
+    beforeRecords: beforeRecords.filter(
+      (record) => changedKeys.has(recordKey(record))
+    ),
+    afterRecords: afterRecords.filter(
+      (record) => changedKeys.has(recordKey(record))
+    )
+  };
+}
+function relationshipTargets(manifest) {
+  const targets = /* @__PURE__ */ new Map();
+  for (const volume of manifest.volumes) {
+    for (const operation of volume.operations) {
+      const relationship = operation.defineRelationship;
+      if (!relationship) continue;
+      targets.set(`${relationship.left}\0${relationship.leftSubmodel}`, {
+        className: relationship.right
+      });
+      targets.set(`${relationship.right}\0${relationship.rightSubmodel}`, {
+        className: relationship.left
+      });
+    }
+  }
+  return targets;
+}
+function stateName(value) {
+  return typeof value === "string" ? value : value.state;
+}
+function asIds(value) {
+  return value === void 0 ? [] : Array.isArray(value) ? value : [value];
+}
+function changedObjectProjection(before, after) {
+  const beforeFields = before?.fields || {};
+  const afterFields = after.fields || {};
+  const fields = { ...afterFields };
+  for (const fieldName of Object.keys(beforeFields)) {
+    if (!(fieldName in afterFields)) fields[fieldName] = null;
+  }
+  if (before && before.label === after.label && stableJson(beforeFields) === stableJson(afterFields)) {
+    return null;
+  }
+  return {
+    kind: "object",
+    operation: before ? "updated" : "created",
+    record: {
+      className: after.className,
+      id: after.id,
+      ...after.label !== void 0 ? { label: after.label } : {},
+      fields
+    }
+  };
+}
+function projectionChanges(input) {
+  const before = new Map(
+    input.beforeRecords.map((record) => [recordKey(record), record])
+  );
+  const after = new Map(
+    input.afterRecords.map((record) => [recordKey(record), record])
+  );
+  const targets = relationshipTargets(input.manifest);
+  const changes = [];
+  for (const record of input.afterRecords) {
+    const previous = before.get(recordKey(record));
+    const objectChange = changedObjectProjection(previous, record);
+    if (objectChange) changes.push(objectChange);
+    const relationshipNames = /* @__PURE__ */ new Set([
+      ...Object.keys(previous?.relationships || {}),
+      ...Object.keys(record.relationships || {})
+    ]);
+    for (const relationshipName of [...relationshipNames].sort()) {
+      const target = targets.get(
+        `${record.className}\0${relationshipName}`
+      );
+      if (!target) {
+        throw new Error(
+          `No ontology relationship target is declared for ${record.className}.${relationshipName}`
+        );
+      }
+      const previousIds = new Set(
+        asIds(previous?.relationships?.[relationshipName])
+      );
+      const currentIds = new Set(
+        asIds(record.relationships?.[relationshipName])
+      );
+      for (const id of [...previousIds].sort()) {
+        if (currentIds.has(id)) continue;
+        changes.push({
+          kind: "relationship",
+          operation: "disconnected",
+          relationship: relationshipName,
+          from: recordReference(record.className, record.id),
+          to: recordReference(target.className, id)
+        });
+      }
+      for (const id of [...currentIds].sort()) {
+        if (previousIds.has(id)) continue;
+        changes.push({
+          kind: "relationship",
+          operation: "connected",
+          relationship: relationshipName,
+          from: recordReference(record.className, record.id),
+          to: recordReference(target.className, id)
+        });
+      }
+    }
+    const machines = /* @__PURE__ */ new Set([
+      ...Object.keys(previous?.states || {}),
+      ...Object.keys(record.states || {})
+    ]);
+    for (const machine of [...machines].sort()) {
+      const next = record.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) {
+        continue;
+      }
+      changes.push({
+        kind: "state_observation",
+        target: recordReference(record.className, record.id),
+        machine,
+        state: stateName(next)
+      });
+    }
+  }
+  for (const record of input.beforeRecords) {
+    if (after.has(recordKey(record))) continue;
+    changes.push({
+      kind: "object",
+      operation: "deleted",
+      target: recordReference(record.className, record.id)
+    });
+  }
+  return changes;
+}
+function valueAtPath(value, path) {
+  return path.split(".").filter(Boolean).reduce((current, segment) => {
+    if (!current || typeof current !== "object" || Array.isArray(current)) {
+      return void 0;
+    }
+    return current[segment];
+  }, value);
+}
+function primaryTarget(input) {
+  if (input.transition) {
+    return recordReference(
+      input.transition.className,
+      input.transition.objectId
+    );
+  }
+  const creates = input.effect.metamodels?.creates;
+  if (creates) {
+    const declaration = typeof creates === "string" ? { className: creates } : creates;
+    const id = declaration.idPath ? valueAtPath(input.result, declaration.idPath) : void 0;
+    if (typeof id === "string" && id) {
+      return recordReference(declaration.className, id);
+    }
+  }
+  if (input.effect.className && !input.effect.static) {
+    const objectId = input.effectInput && typeof input.effectInput === "object" && !Array.isArray(input.effectInput) ? input.effectInput._objectId : void 0;
+    if (typeof objectId === "string" && objectId) {
+      return recordReference(input.effect.className, objectId);
+    }
+  }
+  const created = input.changes.filter(
+    (change) => change.kind === "object" && change.operation === "created"
+  );
+  const onlyCreated = created.length === 1 ? created[0] : void 0;
+  return onlyCreated ? recordReference(onlyCreated.record.className, onlyCreated.record.id) : void 0;
+}
+function transitionOutcome(transition, afterRecords) {
+  if (!transition) {
+    throw new Error("A transition commit has no authored transition context.");
+  }
+  const target = afterRecords.find(
+    (record) => record.className === transition.className && record.id === transition.objectId
+  );
+  const observed = target?.states?.[transition.machine];
+  if (!observed) {
+    throw new Error(
+      `The product result did not expose ${transition.className}:${transition.objectId}.${transition.machine}`
+    );
+  }
+  const finalState = stateName(observed);
+  const matches = Object.entries(transition.outcomes).filter(
+    ([, outcome]) => outcome.to === finalState || outcome.to === "$current" && finalState === transition.from
+  );
+  if (matches.length !== 1) {
+    throw new Error(
+      `Product state ${finalState} maps to ${matches.length} authored outcomes for ${transition.machine}.${transition.transition}`
+    );
+  }
+  const [key, declaration] = matches[0];
+  return {
+    key,
+    ...declaration.disposition === "error" ? {
+      error: {
+        code: `product_outcome_${key}`,
+        message: declaration.label || `The product completed in ${finalState} instead of continuing.`,
+        retryable: false
+      }
+    } : {}
+  };
+}
+function projectRecordSnapshotMutation(input) {
+  const changes = projectionChanges({
+    manifest: input.manifest,
+    beforeRecords: input.source.beforeRecords,
+    afterRecords: input.source.afterRecords,
+    transition: input.transition
+  });
+  const target = primaryTarget({
+    effect: input.effect,
+    effectInput: input.effectInput,
+    result: input.result,
+    changes,
+    transition: input.transition
+  });
+  const base = {
+    source: {
+      reference: input.source.reference,
+      ...input.source.version ? { version: input.source.version } : {}
+    },
+    ...target ? { primaryTarget: target } : {},
+    changes,
+    safeSummary: {
+      effect: input.effect.name,
+      affectedChanges: changes.length
+    }
+  };
+  if (input.commitKind === "effect") return base;
+  return {
+    ...base,
+    outcome: transitionOutcome(input.transition, input.source.afterRecords)
+  };
+}
+
 // src/agent-harness-templates/action-presentation/0.1.0/manifest.json
 var manifest_default = {
   id: "action-presentation",
@@ -22529,10 +23497,15 @@ exports.buildOpenAISpendEventId = buildOpenAISpendEventId;
 exports.buildSessionTranscript = buildSessionTranscript;
 exports.buildSessionTranscriptFromFeedItems = buildSessionTranscriptFromFeedItems;
 exports.calculateOpenAITokenSpend = calculateOpenAITokenSpend;
+exports.canonicalizeCommitValue = canonicalizeCommitValue;
+exports.changedRecordSnapshots = changedRecordSnapshots;
 exports.consumeGranularReasoningOnlyChunk = consumeGranularReasoningOnlyChunk;
 exports.consumeGranularReasoningTraceChunk = consumeGranularReasoningTraceChunk;
 exports.createFeedPublisher = createFeedPublisher;
 exports.createHarnessVerifierSnapshot = createHarnessVerifierSnapshot;
+exports.defineEffect = defineEffect;
+exports.defineProjection = defineProjection;
+exports.defineStateMachine = defineStateMachine;
 exports.emitFeedDiagnostic = emitFeedDiagnostic;
 exports.emitFeedDiagnosticToDefaultSink = emitFeedDiagnosticToDefaultSink;
 exports.emptyFeedSnapshot = emptyFeedSnapshot;
@@ -22565,6 +23538,7 @@ exports.projectConversationReferentFocus = projectConversationReferentFocus;
 exports.projectConversationReferentSummary = projectConversationReferentSummary;
 exports.projectHeapSummary = projectHeapSummary;
 exports.projectLoopSummary = projectLoopSummary;
+exports.projectRecordSnapshotMutation = projectRecordSnapshotMutation;
 exports.projectSessionFileSummary = projectSessionFileSummary;
 exports.projectWorkflowFocus = projectWorkflowFocus;
 exports.projectWorkflowSummary = projectWorkflowSummary;
@@ -22582,6 +23556,7 @@ exports.scorePromptChoiceMatch = scorePromptChoiceMatch;
 exports.stripGranularReasoningTrace = stripGranularReasoningTrace;
 exports.toGranularHttpBase = toGranularHttpBase;
 exports.validateHarnessTemplateManifest = validateHarnessTemplateManifest;
+exports.validateProjectionResult = validateProjectionResult;
 exports.validationRuleFailureMessage = validationRuleFailureMessage;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map