alchemy 2.0.0-beta.30 → 2.0.0-beta.32

package/src/AWS/Website/AssetDeployment.ts

@@ -101,7 +101,7 @@ export const AssetDeploymentProvider = () =>
   Provider.effect(
     AssetDeployment,
     Effect.gen(function* () {
-      const sync = Effect.fn(function* (news: AssetDeploymentProps) {
+      const reconcileSync = Effect.fn(function* (news: AssetDeploymentProps) {
         const bucketName = news.bucket.bucketName;
         const prefix = normalizePrefix(news.prefix);
         const root = news.sourcePath;
@@ -109,6 +109,14 @@ export const AssetDeploymentProvider = () =>
         const hash = createHash("sha256");
         const desiredKeys = new Set<string>();
 
+        // Observe — list every key already under the prefix and capture
+        // its ETag (S3 ETag for non-multipart PUTs is the hex MD5 of the
+        // body) so we can skip re-uploads when the content already matches.
+        const observed = yield* listObjects(
+          bucketName,
+          prefix ? `${prefix}/` : prefix,
+        );
+
         for (const relativePath of files.sort((a, b) => a.localeCompare(b))) {
           const body = yield* Effect.tryPromise(() =>
             readFile(path.join(root, relativePath)),
@@ -130,6 +138,15 @@ export const AssetDeploymentProvider = () =>
 
           desiredKeys.add(key);
 
+          // Sync — diff observed object hash against desired body hash,
+          // and only PUT when the content has changed. ETag is wrapped in
+          // quotes by S3 and is lower-case hex.
+          const expectedETag = createHash("md5").update(body).digest("hex");
+          const observedETag = observed.get(key)?.replace(/^"|"$/g, "");
+          if (observedETag === expectedETag) {
+            continue;
+          }
+
           yield* s3.putObject({
             Bucket: bucketName,
             Key: key,
@@ -139,12 +156,12 @@ export const AssetDeploymentProvider = () =>
           });
         }
 
+        // Sync purge — delete observed keys that aren't in the desired
+        // set. Reuses the same observation rather than re-listing.
         if (news.purge ?? false) {
-          const existingKeys = yield* listKeys(
-            bucketName,
-            prefix ? `${prefix}/` : prefix,
+          const staleKeys = [...observed.keys()].filter(
+            (key) => !desiredKeys.has(key),
           );
-          const staleKeys = existingKeys.filter((key) => !desiredKeys.has(key));
           yield* deleteKeys(bucketName, staleKeys);
         }
 
@@ -160,15 +177,8 @@ export const AssetDeploymentProvider = () =>
         read: Effect.fn(function* ({ output }) {
           return output;
         }),
-        create: Effect.fn(function* ({ news, session }) {
-          const output = yield* retryForBucketReadiness(sync(news));
-          yield* session.note(
-            `Uploaded ${output.fileCount} file(s) to s3://${output.bucketName}/${output.prefix}`,
-          );
-          return output;
-        }),
-        update: Effect.fn(function* ({ news, session }) {
-          const output = yield* retryForBucketReadiness(sync(news));
+        reconcile: Effect.fn(function* ({ news, session }) {
+          const output = yield* retryForBucketReadiness(reconcileSync(news));
           yield* session.note(
             `Uploaded ${output.fileCount} file(s) to s3://${output.bucketName}/${output.prefix}`,
           );
@@ -318,6 +328,29 @@ const listKeys = Effect.fn(function* (bucketName: string, prefix: string) {
   return keys;
 });
 
+/** List `{key -> ETag}` pairs under `prefix`. ETag from S3 is wrapped in
+ * quotes; for non-multipart uploads it is the hex MD5 of the object body. */
+const listObjects = Effect.fn(function* (bucketName: string, prefix: string) {
+  let continuationToken: string | undefined;
+  const out = new Map<string, string>();
+
+  do {
+    const response = yield* s3.listObjectsV2({
+      Bucket: bucketName,
+      Prefix: prefix || undefined,
+      ContinuationToken: continuationToken,
+    });
+    for (const item of response.Contents ?? []) {
+      if (item.Key && item.ETag) {
+        out.set(item.Key, item.ETag);
+      }
+    }
+    continuationToken = response.NextContinuationToken;
+  } while (continuationToken);
+
+  return out;
+});
+
 const deleteKeys = Effect.fn(function* (bucketName: string, keys: string[]) {
   for (let i = 0; i < keys.length; i += 1000) {
     const batch = keys.slice(i, i + 1000);

package/src/AWS/index.ts

@@ -8,6 +8,7 @@ export * from "./Providers.ts";
 export { Region } from "@distilled.cloud/aws/Region";
 
 export * as ACM from "./ACM/index.ts";
+export * as ApiGateway from "./ApiGateway/index.ts";
 export * as AutoScaling from "./AutoScaling/index.ts";
 export * as CloudFront from "./CloudFront/index.ts";
 export * as CloudWatch from "./CloudWatch/index.ts";

package/src/AdoptPolicy.ts

@@ -1,10 +1,133 @@
 import * as Context from "effect/Context";
+import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 
+/**
+ * AdoptPolicy controls whether the engine should "adopt" pre-existing cloud
+ * resources that conflict with this stack instead of failing.
+ *
+ * The engine always calls a provider's `read` lifecycle operation when there
+ * is no prior state and `read` is implemented. The provider's job is to
+ * report two things:
+ *
+ *   1. Whether the resource exists (returns attributes vs. `undefined`).
+ *   2. Whether *we* own it (plain attributes vs. {@link Unowned}-branded).
+ *
+ * The engine then routes:
+ *
+ *   | `read` outcome      | `adopt: false` | `adopt: true`     |
+ *   | ------------------- | -------------- | ----------------- |
+ *   | undefined           | create         | create            |
+ *   | owned (plain attrs) | silent adopt   | silent adopt      |
+ *   | {@link Unowned}     | fail           | takeover (adopt)  |
+ *
+ * "Owned" means a provider has affirmatively determined the resource was
+ * created by this stack/stage/logical-id (typically by inspecting tags or
+ * naming conventions). Resources without ownership semantics simply always
+ * return plain attrs — they are treated as owned by default, so silent
+ * adoption is the norm and `--adopt` is unnecessary.
+ *
+ * The policy can be overridden per-effect via {@link adopt} — most commonly
+ * applied at the resource or stack scope.
+ */
 export class AdoptPolicy extends Context.Service<AdoptPolicy, boolean>()(
   "AdoptPolicy",
 ) {}
 
+/**
+ * Engine-raised failure produced when `read` reports an existing resource
+ * marked as {@link Unowned} and `adopt` is `false`. Surface this to the user
+ * to indicate they should either re-tag the cloud resource, pick a different
+ * physical name, or re-run with `--adopt` (or `adopt(true)`) to force a
+ * takeover.
+ */
+export class OwnedBySomeoneElse extends Data.TaggedError("OwnedBySomeoneElse")<{
+  /** A human-readable description of why the resource cannot be adopted. */
+  message: string;
+  /** The Resource Type (e.g. `AWS.S3.Bucket`). */
+  resourceType?: string;
+  /** The logical ID of the conflicting resource. */
+  logicalId?: string;
+  /** The physical name/identifier of the conflicting resource. */
+  physicalName?: string;
+}> {}
+
+/**
+ * Private symbol used to brand attribute objects returned by `read` as
+ * "exists in cloud, but not owned by this stack/stage/logical-id".
+ *
+ * Deliberately *not* registered via `Symbol.for` — the brand is an
+ * engine-internal routing hint and must not be observable or
+ * forgeable from outside this module. The engine strips it before any
+ * state persistence (see {@link stripUnowned}) so it never leaks into
+ * the state store, JSON serialization, or downstream `Output`s.
+ */
+const UnownedTag: unique symbol = Symbol("alchemy/Unowned");
+
+/**
+ * Brand a `read` return value as belonging to a different owner.
+ *
+ * Use this in a provider's `read` implementation when the resource exists in
+ * the cloud but a positive ownership check (e.g. tag inspection) shows it
+ * was *not* created by this stack/stage/logical-id:
+ *
+ * ```ts
+ * read: Effect.fnUntraced(function* ({ id, output, olds }) {
+ *   const settings = yield* getScriptSettings({ ... }).pipe(
+ *     Effect.catchTag("WorkerNotFound", () => Effect.succeed(undefined)),
+ *   );
+ *   if (!settings) return undefined;
+ *
+ *   const attrs = { workerName, ...buildAttrs(settings) };
+ *   return hasAlchemyWorkerTags(id, settings.tags) ? attrs : Unowned(attrs);
+ * }),
+ * ```
+ *
+ * The returned value is structurally still `T` — there is no wrapper to
+ * unwrap. The brand is a non-enumerable symbol that the engine inspects
+ * during planning to decide whether to take over (`adopt: true`) or fail
+ * loudly (`adopt: false`).
+ *
+ * Resources without ownership semantics should simply return plain attrs —
+ * the engine treats them as owned and silent adoption is the default.
+ */
+export const Unowned: {
+  <T extends object>(attrs: T): T;
+  is: (value: unknown) => boolean;
+} = Object.assign(
+  <T extends object>(attrs: T): T => {
+    const cloned = { ...attrs } as T;
+    Object.defineProperty(cloned, UnownedTag, {
+      value: true,
+      enumerable: false,
+      writable: false,
+      configurable: false,
+    });
+    return cloned;
+  },
+  {
+    is: (value: unknown): boolean =>
+      typeof value === "object" &&
+      value !== null &&
+      (value as any)[UnownedTag] === true,
+  },
+);
+
+/**
+ * Strip the {@link Unowned} brand from an attributes object before persisting
+ * it — state should not carry per-deploy ownership-routing metadata.
+ *
+ * The brand is intentionally non-enumerable, so a plain spread already
+ * drops it; the additional `delete` is defense-in-depth in case a future
+ * change makes the descriptor enumerable. Always returns a fresh object
+ * (never mutates the input).
+ */
+export const stripUnowned = <T extends object>(attrs: T): T => {
+  const out: any = { ...attrs };
+  if (UnownedTag in out) delete out[UnownedTag];
+  return out;
+};
+
 export const adopt: {
   (
     enabled?: boolean,

package/src/AlchemyContext.ts

@@ -10,6 +10,17 @@ export class AlchemyContext extends EffectContext.Service<
     dotAlchemy: string;
     updateStateStore: boolean;
     dev: boolean;
+    /**
+     * Global default for the {@link import("./AdoptPolicy.ts").AdoptPolicy}
+     * service. When `true`, resources without prior state will be adopted by
+     * calling their `read` lifecycle operation; if that returns attributes
+     * (and does not fail with `OwnedBySomeoneElse`), those attributes are
+     * persisted as the resource's initial `created` state.
+     *
+     * The CLI's `--adopt` flag flows in through this field. Per-resource
+     * overrides via the `adopt(enabled)` combinator still take precedence.
+     */
+    adopt: boolean;
   }
 >()("alchemy/Context") {}
 
@@ -24,6 +35,7 @@ export const AlchemyContextLive = Layer.effect(
       dotAlchemy: dir,
       updateStateStore: false,
       dev: false,
+      adopt: false,
     };
   }),
 );

package/src/Apply.ts

@@ -523,12 +523,13 @@ const executeNode = (
         );
 
         attr = yield* node.provider
-          .create({
+          .reconcile({
             id: logicalId,
             news,
             instanceId,
             bindings: bindingOutputs,
             session: scopedSession,
+            olds: undefined,
             output: attr,
           })
           .pipe(
@@ -640,14 +641,13 @@ const executeNode = (
         );
 
         const attr = yield* node.provider
-          .update({
+          .reconcile({
             id: logicalId,
             news,
             instanceId,
             bindings: bindingOutputs,
             session: scopedSession,
             olds: previousProps,
-            // @ts-expect-error - type system says this can be undefined, can it be?
             output: node.state.attr,
           })
           .pipe(
@@ -811,12 +811,13 @@ const executeNode = (
         );
 
         attr = yield* node.provider
-          .create({
+          .reconcile({
             id: logicalId,
             news,
             instanceId,
             bindings: bindingOutputs,
             session: scopedSession,
+            olds: undefined,
             output: attr,
           })
           .pipe(
@@ -904,7 +905,7 @@ const executeNode = (
 // After the initial concurrent pass, some resources may have been created
 // with stale upstream values (e.g. a precreate stub instead of the final
 // output). Walk the plan and re-evaluate each resource's props/bindings
-// against the current tracker outputs. Call provider.update for any
+// against the current tracker outputs. Call provider.reconcile for any
 // resource whose resolved inputs differ from what it was last applied with.
 // Repeat until no resource needs updating.
 
@@ -973,7 +974,7 @@ const converge = Effect.fnUntraced(function* (
       } satisfies ScopedPlanStatusSession;
 
       const attr = yield* node.provider
-        .update({
+        .reconcile({
           id: logicalId,
           news: newProps,
           instanceId,

package/src/Axiom/Annotation.ts

@@ -67,12 +67,31 @@ export const AnnotationProvider = () =>
 
       return {
         stables: ["id"],
-        create: Effect.fn(function* ({ news }) {
-          return yield* create(news);
-        }),
-        update: Effect.fn(function* ({ news, output }) {
-          const result = yield* update({ ...news, id: output.id });
-          return { ...result, id: output.id, time: result.time ?? output.time };
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // Observe — Axiom assigns the annotation id server-side, so the
+          // only handle to a previously-created annotation is the cached
+          // `output.id`. Probe for live state with that id; treat NotFound
+          // (deleted out-of-band, or never created) as "no observed state".
+          const observed = output?.id
+            ? yield* get({ id: output.id }).pipe(
+                Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+              )
+            : undefined;
+
+          // Ensure — when no observed annotation exists, POST creates one
+          // and Axiom assigns the id.
+          if (observed === undefined) {
+            return yield* create(news);
+          }
+
+          // Sync — the annotation exists; apply desired props with PUT and
+          // preserve the stable id and original time as fallbacks.
+          const result = yield* update({ ...news, id: observed.id! });
+          return {
+            ...result,
+            id: observed.id!,
+            time: result.time ?? output?.time ?? news.time,
+          };
         }),
         delete: Effect.fn(function* ({ output }) {
           yield* del({ id: output.id }).pipe(

package/src/Axiom/ApiToken.ts

@@ -91,7 +91,21 @@ export const ApiTokenProvider = () =>
           if (deepEqual(olds, news)) return undefined;
           return { action: "replace" } as const;
         }),
-        create: Effect.fn(function* ({ news }) {
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // Observe — Axiom does not expose an update endpoint for tokens,
+          // so any actual change to the inputs is forced to a replacement
+          // by `diff` above. That means by the time `reconcile` runs we
+          // are either (a) creating fresh, or (b) re-reconciling identical
+          // inputs against an existing token.
+          if (output !== undefined) {
+            // Identical inputs — Axiom does not echo the bearer back, so
+            // the cached `output` (with the persisted Redacted token) is
+            // the authoritative current state.
+            return output;
+          }
+
+          // Ensure — mint a new token. Axiom returns the bearer exactly
+          // once; capture it into Redacted state for downstream consumers.
           const result = yield* create(news);
           if (!result.token) {
             return yield* Effect.die(
@@ -103,11 +117,6 @@ export const ApiTokenProvider = () =>
             token: Redacted.make(result.token),
           };
         }),
-        update: Effect.fn(function* ({ output }) {
-          // Diff returns "replace" for every change, so update should never
-          // run. If invoked, just return current state unchanged.
-          return output;
-        }),
         delete: Effect.fn(function* ({ output }) {
           yield* del({ id: output.id }).pipe(
             Effect.catchTag("NotFound", () => Effect.void),

package/src/Axiom/Dashboard.ts

@@ -161,15 +161,27 @@ export const DashboardProvider = () =>
 
       return {
         stables: ["uid", "id", "createdAt", "createdBy"],
-        create: Effect.fn(function* ({ news }) {
-          return toAttrsFromCreate(yield* create(news));
-        }),
-        update: Effect.fn(function* ({ news, output }) {
-          // `overwrite: true` short-circuits Axiom's optimistic-concurrency
-          // check (otherwise the API requires the caller to echo back the
-          // server-side `version`, which the resource state doesn't track).
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // Observe — `uid` is server-assigned at create time. We probe
+          // Axiom for the dashboard via the cached uid; treat NotFound
+          // (deleted out-of-band) as "no observed state" so we converge
+          // by re-creating.
+          const observed = output?.uid
+            ? yield* get({ uid: output.uid }).pipe(
+                Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+              )
+            : undefined;
+
+          // Ensure — POST mints a new dashboard with a fresh uid.
+          if (observed === undefined) {
+            return toAttrsFromCreate(yield* create(news));
+          }
+
+          // Sync — `overwrite: true` short-circuits Axiom's optimistic-
+          // concurrency check (otherwise the API requires the caller to
+          // echo back the server-side `version`, which we don't track).
           return toAttrsFromCreate(
-            yield* update({ ...news, uid: output.uid, overwrite: true }),
+            yield* update({ ...news, uid: observed.uid, overwrite: true }),
           );
         }),
         delete: Effect.fn(function* ({ output }) {

package/src/Axiom/Dataset.ts

@@ -1,8 +1,7 @@
 import * as Axiom from "@distilled.cloud/axiom";
 import { Credentials } from "@distilled.cloud/axiom/Credentials";
 import * as Effect from "effect/Effect";
-import * as Option from "effect/Option";
-import { AdoptPolicy } from "../AdoptPolicy.ts";
+import { Unowned } from "../AdoptPolicy.ts";
 import { isResolved } from "../Diff.ts";
 import * as Provider from "../Provider.ts";
 import { Resource } from "../Resource.ts";
@@ -202,85 +201,100 @@ export const DatasetProvider = () =>
           }
           return undefined;
         }),
-        create: Effect.fn(function* ({ id, news }) {
+        reconcile: Effect.fn(function* ({ id, news, output }) {
           const stack = yield* Stack;
           const stage = yield* Stage;
-          const adoptPolicy = yield* Effect.serviceOption(AdoptPolicy).pipe(
-            Effect.map(Option.getOrElse(() => false)),
-          );
           const marker = buildMarker(stack.name, stage, id);
-          const dataset = yield* (
-            create({
-              name: news.name,
-              description: augmentDescription(news.description, marker),
-              kind: news.kind,
-              retentionDays: news.retentionDays,
-              useRetentionPeriod: news.useRetentionPeriod,
-            }) as Effect.Effect<
-              Axiom.CreateDatasetOutput,
-              { readonly _tag: string },
-              never
-            >
-          ).pipe(
-            Effect.catchIf(
-              (e): e is { readonly _tag: "Conflict" | "UnprocessableEntity" } =>
-                e._tag === "Conflict" || e._tag === "UnprocessableEntity",
-              () =>
-                Effect.gen(function* () {
-                  const existing = yield* get({ dataset_id: news.name });
-                  const ownership = parseMarker(existing.description);
-                  const isOurs =
-                    ownership !== undefined &&
-                    ownership.stack === stack.name &&
-                    ownership.stage === stage &&
-                    ownership.id === id;
-                  if (isOurs || adoptPolicy) {
-                    // Re-apply the user's desired props (and re-stamp marker)
-                    // so adoption is idempotent and Axiom-side state matches
-                    // the resource spec.
-                    return yield* update({
-                      dataset_id: existing.id,
-                      description: augmentDescription(news.description, marker),
-                      retentionDays: news.retentionDays,
-                      useRetentionPeriod: news.useRetentionPeriod,
-                    });
-                  }
-                  return yield* Effect.die(
-                    new Error(
-                      `Axiom dataset "${news.name}" already exists and was ` +
-                        `not created by this stack (${stack.name}/${stage}/${id}). ` +
-                        `Pipe the resource through \`adopt()\` from "alchemy/AdoptPolicy" ` +
-                        `to take ownership, or delete the dataset in Axiom and retry.`,
-                    ),
-                  );
-                }),
-            ),
+
+          // Observe — Axiom's dataset path identifier is `name`, which is
+          // also stable input. Probe for live state by name (preferring the
+          // cached `output.id` when present). `read` upstream has already
+          // surfaced foreign datasets as `Unowned`, so by the time we land
+          // here mutation is safe.
+          const datasetId = output?.id ?? news.name;
+          const observed = yield* get({ dataset_id: datasetId }).pipe(
+            Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
           );
-          return toAttrs(dataset);
-        }),
-        update: Effect.fn(function* ({ id, news, output }) {
-          const stack = yield* Stack;
-          const stage = yield* Stage;
-          const marker = buildMarker(stack.name, stage, id);
-          const dataset = yield* update({
-            dataset_id: output.id,
-            description: augmentDescription(news.description, marker),
+
+          // Ensure — POST creates the dataset. Tolerate Conflict/
+          // UnprocessableEntity as a race with a peer reconciler (or with
+          // upstream read↔create), falling through to the sync path.
+          let current = observed;
+          if (current === undefined) {
+            current = yield* (
+              create({
+                name: news.name,
+                description: augmentDescription(news.description, marker),
+                kind: news.kind,
+                retentionDays: news.retentionDays,
+                useRetentionPeriod: news.useRetentionPeriod,
+              }) as Effect.Effect<
+                Axiom.CreateDatasetOutput,
+                { readonly _tag: string },
+                never
+              >
+            ).pipe(
+              Effect.catchIf(
+                (
+                  e,
+                ): e is { readonly _tag: "Conflict" | "UnprocessableEntity" } =>
+                  e._tag === "Conflict" || e._tag === "UnprocessableEntity",
+                () =>
+                  update({
+                    dataset_id: news.name,
+                    description: augmentDescription(news.description, marker),
+                    retentionDays: news.retentionDays,
+                    useRetentionPeriod: news.useRetentionPeriod,
+                  }),
+              ),
+            );
+            return toAttrs(current);
+          }
+
+          // Sync — the dataset exists. Apply mutable aspects (description,
+          // retentionDays, useRetentionPeriod) via PATCH. `kind` and `name`
+          // are stable and replacement-only via diff above.
+          const desiredDescription = augmentDescription(
+            news.description,
+            marker,
+          );
+          const needsSync =
+            current.description !== desiredDescription ||
+            current.retentionDays !== news.retentionDays ||
+            current.useRetentionPeriod !== news.useRetentionPeriod;
+          if (!needsSync) {
+            return toAttrs(current);
+          }
+          const updated = yield* update({
+            dataset_id: current.id,
+            description: desiredDescription,
             retentionDays: news.retentionDays,
             useRetentionPeriod: news.useRetentionPeriod,
           });
-          return toAttrs(dataset);
+          return toAttrs(updated);
         }),
         delete: Effect.fn(function* ({ output }) {
           yield* del({ dataset_id: output.id }).pipe(
             Effect.catchTag("NotFound", () => Effect.void),
           );
         }),
-        read: Effect.fn(function* ({ output }) {
-          if (!output?.id) return undefined;
-          return yield* get({ dataset_id: output.id }).pipe(
-            Effect.map(toAttrs),
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const stack = yield* Stack;
+          const stage = yield* Stage;
+          const datasetId = output?.id ?? olds?.name;
+          if (!datasetId) return undefined;
+          const existing = yield* get({ dataset_id: datasetId }).pipe(
             Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
           );
+          if (!existing) return undefined;
+          const ownership = parseMarker(existing.description);
+          const isOurs =
+            ownership !== undefined &&
+            ownership.stack === stack.name &&
+            ownership.stage === stage &&
+            ownership.id === id;
+          const attrs = toAttrs(existing);
+          return isOurs ? attrs : Unowned(attrs);
         }),
       };
     }),

package/src/Axiom/Monitor.ts

@@ -100,11 +100,26 @@ export const MonitorProvider = () =>
           }
           return undefined;
         }),
-        create: Effect.fn(function* ({ news }) {
-          return yield* create(news);
-        }),
-        update: Effect.fn(function* ({ news, output }) {
-          return yield* update({ ...news, id: output.id });
+        reconcile: Effect.fn(function* ({ news, output }) {
+          // Observe — Axiom assigns the monitor id server-side, so the only
+          // handle to a previously-created monitor is the cached
+          // `output.id`. Probe for live state with that id; treat NotFound
+          // (deleted out-of-band) as "no observed state" so we converge by
+          // re-creating.
+          const observed = output?.id
+            ? yield* get({ id: output.id }).pipe(
+                Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+              )
+            : undefined;
+
+          // Ensure — POST mints a new monitor with a fresh id.
+          if (observed === undefined) {
+            return yield* create(news);
+          }
+
+          // Sync — the monitor exists; PATCH against its id with the
+          // desired props. `type` is replacement-only (handled in diff).
+          return yield* update({ ...news, id: observed.id });
         }),
         delete: Effect.fn(function* ({ output }) {
           yield* del({ id: output.id }).pipe(