alchemy 2.0.0-beta.30 → 2.0.0-beta.31

package/bin/exec.js

@@ -12,9 +12,9 @@ import * as Logger from "effect/Logger";
 import * as Option from "effect/Option";
 import * as Command from "effect/unstable/cli/Command";
 import * as Flag from "effect/unstable/cli/Flag";
+import * as Data from "effect/Data";
 import * as Cause from "effect/Cause";
 import * as Deferred from "effect/Deferred";
-import * as Data from "effect/Data";
 import { pipe } from "effect/Function";
 import * as Redacted from "effect/Redacted";
 import { SingleShotGen } from "effect/Utils";
@@ -40,7 +40,8 @@ const AlchemyContextLive = Layer.effect(AlchemyContext, Effect.gen(function* ()
 	return {
 		dotAlchemy: dir,
 		updateStateStore: false,
-		dev: false
+		dev: false,
+		adopt: false
 	};
 }));
 
@@ -63,7 +64,105 @@ const runMain = (effect, options) => {
 
 //#endregion
 //#region lib/AdoptPolicy.js
+/**
+* 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.
+*/
 var AdoptPolicy = class extends EffectContext.Service()("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.
+*/
+var OwnedBySomeoneElse = class extends Data.TaggedError("OwnedBySomeoneElse") {};
+/**
+* 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 = 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.
+*/
+const Unowned = Object.assign((attrs) => {
+	const cloned = { ...attrs };
+	Object.defineProperty(cloned, UnownedTag, {
+		value: true,
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	return cloned;
+}, { is: (value) => typeof value === "object" && value !== null && value[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).
+*/
+const stripUnowned = (attrs) => {
+	const out = { ...attrs };
+	if (UnownedTag in out) delete out[UnownedTag];
+	return out;
+};
 
 //#endregion
 //#region lib/Artifacts.js
@@ -129,19 +228,6 @@ const ensureArtifactStore = (effect) => Effect.serviceOption(ArtifactStore).pipe
 //#region lib/Cli/Cli.js
 var Cli = class extends EffectContext.Service()("CLI") {};
 
-//#endregion
-//#region lib/Util/service.js
-const GenericService = () => (Kind) => {
-	const service = EffectContext.Service(Kind);
-	const make$2 = (Type) => EffectContext.Service(`${Kind}<${Type}>`);
-	return Object.assign(Object.setPrototypeOf(make$2, service), service);
-};
-
-//#endregion
-//#region lib/ExecutionContext.js
-const ExecutionContext = GenericService()("Alchemy::ExecutionContext");
-const CurrentExecutionContext = Effect.serviceOption(ExecutionContext).pipe(Effect.map(Option.getOrUndefined));
-
 //#endregion
 //#region lib/Ref.js
 const RefMetadata = Symbol.for("alchemy/RefMetadata");
@@ -239,6 +325,14 @@ const tryFindProviderByType = Effect.fnUntraced(function* (resourceType) {
 	return Option.none();
 });
 
+//#endregion
+//#region lib/Util/service.js
+const GenericService = () => (Kind) => {
+	const service = EffectContext.Service(Kind);
+	const make$2 = (Type) => EffectContext.Service(`${Kind}<${Type}>`);
+	return Object.assign(Object.setPrototypeOf(make$2, service), service);
+};
+
 //#endregion
 //#region lib/Auth/Profile.js
 const rootDir = path.join(os.homedir(), ".alchemy");
@@ -352,7 +446,6 @@ const make$1 = (options) => (effect) => Effect.scope.pipe(Effect.flatMap((scope)
 })), Effect.provideContext(context))));
 const CurrentStack = Effect.serviceOption(Stack).asEffect().pipe(Effect.map(Option.getOrUndefined));
 const platform = Layer.mergeAll(PlatformServices, FetchHttpClient.layer, Logger.layer([fileLogger("out")], { mergeWithExisting: true }));
-const alchemy = Layer.mergeAll(AlchemyContextLive);
 
 //#endregion
 //#region lib/Resource.js
@@ -360,6 +453,16 @@ const isResource = (value) => {
 	return typeof value === "object" && value !== null && "Type" in value;
 };
 
+//#endregion
+//#region lib/RuntimeContext.js
+/**
+* Context of the runtime environment.
+*
+* E.g. the context of a running Worker, Task, Process, Function
+*/
+const RuntimeContext = GenericService()("Alchemy::RuntimeContext");
+const CurrentRuntimeContext = Effect.serviceOption(RuntimeContext).pipe(Effect.map(Option.getOrUndefined));
+
 //#endregion
 //#region lib/State/State.js
 var State = class extends EffectContext.Service()("alchemy/State") {};
@@ -393,7 +496,7 @@ var BaseExpr = class {
 		return this.bind(this.toString());
 	}
 	bind(id) {
-		return ExecutionContext.asEffect().pipe(Effect.flatMap((ctx) => Effect.map(ctx.set(id, this), (key) => ctx.get(key))));
+		return RuntimeContext.asEffect().pipe(Effect.flatMap((ctx) => Effect.map(ctx.set(id, this), (key) => ctx.get(key))));
 	}
 	pipe(...fns) {
 		return pipe(this, ...fns);
@@ -605,6 +708,14 @@ const toObject = (acc, v) => ({
 
 //#endregion
 //#region lib/Diff.js
+const isResolved = (value) => !_hasUnresolved(value);
+const _hasUnresolved = (value) => {
+	if (value == null || isPrimitive(value)) return false;
+	if (isExpr(value) || Effect.isEffect(value)) return true;
+	if (Array.isArray(value)) return value.some(_hasUnresolved);
+	if (typeof value === "object") return Object.values(value).some(_hasUnresolved);
+	return false;
+};
 const havePropsChanged = (oldProps, newProps) => hasOutputs(newProps) || JSON.stringify(canonicalize(oldProps ?? {})) !== JSON.stringify(canonicalize(newProps ?? {}));
 const canonicalize = (value) => {
 	if (Array.isArray(value)) return value.map(canonicalize);
@@ -645,6 +756,84 @@ const generateInstanceId = () => Effect.sync(() => {
 //#region lib/Util/types.js
 const asEffect = (effect) => Effect.isEffect(effect) ? effect : Effect.succeed(effect);
 
+//#endregion
+//#region lib/Telemetry/Metrics.js
+/**
+* Counter for resource lifecycle operations. Tagged per call with
+* `resource_type`, `op` (`precreate`/`create`/`update`/`delete`/`read`),
+* and `status` (`success`/`error`).
+*/
+const resourceCounter = Metric.counter("alchemy.resource.operations", {
+	description: "Number of resource lifecycle operations dispatched by alchemy apply.",
+	incremental: true
+});
+/**
+* Histogram of how long each lifecycle operation takes.
+*/
+const resourceDuration = Metric.timer("alchemy.resource.duration", { description: "Wall-clock duration of resource lifecycle operations dispatched by alchemy apply." });
+/**
+* Counter for CLI command invocations.
+*/
+const cliCounter = Metric.counter("alchemy.cli.invocations", {
+	description: "Number of alchemy CLI command invocations.",
+	incremental: true
+});
+/**
+* Counter for Cloudflare State Store bootstrap/deploy operations.
+* Tagged per call with `op` (e.g. `deploy`) and `status`
+* (`success`/`error`) so that the deploy success rate of the
+* state store itself can be tracked separately from regular
+* resource lifecycle ops.
+*/
+const stateStoreCounter = Metric.counter("alchemy.state_store.operations", {
+	description: "Number of Cloudflare State Store deploy/bootstrap operations dispatched by alchemy.",
+	incremental: true
+});
+/**
+* Counter for State store layer construction. Tagged with `id` (the
+* `StateService.id` slug) so we can answer "how many distinct projects
+* are using each backend" from the corresponding `state_store.init`
+* spans. Open-ended on purpose: third-party state stores get counted
+* automatically by setting their `StateService.id`.
+*/
+const stateStoreInitCounter = Metric.counter("alchemy.state_store.inits", {
+	description: "Number of times a State store layer is constructed.",
+	incremental: true
+});
+/**
+* Wraps a resource lifecycle Effect to record a counter + timer entry,
+* tagged with `resource_type`, `op`, and `status` (`success`/`error`).
+*
+* Usage:
+* ```ts
+* provider.reconcile(input).pipe(recordResourceOp(node.resource.Type, "create"))
+* ```
+*/
+const recordResourceOp = (resourceType, op) => (self) => Effect.suspend(() => {
+	const startNs = process.hrtime.bigint();
+	const baseAttrs = {
+		resource_type: resourceType,
+		op
+	};
+	return self.pipe(Effect.onExit((exit) => recordOutcome(baseAttrs, Exit.isSuccess(exit) ? "success" : "error", elapsed(startNs))));
+});
+/**
+* Wraps a CLI command Effect to bump {@link cliCounter} with the
+* outcome (`success`/`error`).
+*/
+const recordCli = (command) => (self) => self.pipe(Effect.onExit((exit) => Metric.update(Metric.withAttributes(cliCounter, {
+	command,
+	status: Exit.isSuccess(exit) ? "success" : "error"
+}), 1)));
+const elapsed = (startNs) => Duration.nanos(process.hrtime.bigint() - startNs);
+const recordOutcome = (baseAttrs, status, duration) => {
+	const attrs = {
+		...baseAttrs,
+		status
+	};
+	return Effect.all([Metric.update(Metric.withAttributes(resourceCounter, attrs), 1), Metric.update(Metric.withAttributes(resourceDuration, attrs), duration)], { discard: true });
+};
+
 //#endregion
 //#region lib/Util/scc.js
 /**
@@ -725,6 +914,15 @@ const make = (stack, options = {}) => Effect.gen(function* () {
 	const resources = Object.values(stack.resources);
 	const stackName = stack.name;
 	const stage$1 = stack.stage;
+	const shouldAdopt = Effect.gen(function* () {
+		const fromService = yield* Effect.serviceOption(AdoptPolicy);
+		if (Option.isSome(fromService)) return fromService.value;
+		const ctx = yield* Effect.serviceOption(AlchemyContext);
+		return Option.match(ctx, {
+			onNone: () => false,
+			onSome: (c) => c.adopt
+		});
+	});
 	const resourceFqns = yield* state.list({
 		stack: stackName,
 		stage: stage$1
@@ -812,11 +1010,50 @@ const make = (stack, options = {}) => Effect.gen(function* () {
 		const news = yield* resolveInput(resource.Props);
 		const downstream = newDownstreamDependencies[fqn] ?? [];
 		const newBindings = yield* resolveInput(stack.bindings[fqn] ?? []);
-		const oldState = yield* state.get({
+		let oldState = yield* state.get({
 			stack: stackName,
 			stage: stage$1,
 			fqn
 		});
+		let forceUpdateAfterAdoption = false;
+		if (oldState === void 0 && provider.read && isResolved(news)) {
+			const adoptInstanceId = yield* generateInstanceId();
+			const readResult = yield* provider.read({
+				id,
+				instanceId: adoptInstanceId,
+				olds: news,
+				output: void 0
+			}).pipe(providePlanScope(fqn, adoptInstanceId));
+			if (readResult !== void 0) {
+				if (Unowned.is(readResult) && !(yield* shouldAdopt)) return yield* new OwnedBySomeoneElse({
+					message: `Cannot adopt resource '${fqn}' (${resource.Type}): it exists in the cloud but is not owned by this stack/stage/logical-id. Re-run with \`--adopt\` (or wrap the effect in \`adopt(true)\`) to take it over.`,
+					resourceType: resource.Type,
+					logicalId: id
+				});
+				const adoptedState = {
+					status: "created",
+					fqn,
+					logicalId: id,
+					instanceId: adoptInstanceId,
+					namespace: resource.Namespace,
+					resourceType: resource.Type,
+					props: news,
+					attr: stripUnowned(readResult),
+					providerVersion: provider.version ?? 0,
+					bindings: [],
+					downstream,
+					removalPolicy: resource.RemovalPolicy
+				};
+				yield* state.set({
+					stack: stackName,
+					stage: stage$1,
+					fqn,
+					value: adoptedState
+				});
+				oldState = adoptedState;
+				forceUpdateAfterAdoption = true;
+			}
+		}
 		const oldBindings = oldState?.bindings ?? [];
 		const bindingDiffs = diffBindings(oldBindings, newBindings);
 		const Node = (node) => ({
@@ -858,7 +1095,7 @@ const make = (stack, options = {}) => Effect.gen(function* () {
 			news,
 			oldBindings,
 			newBindings
-		}).pipe(providePlanScope(fqn, oldState.instanceId))).pipe(Effect.map((diff$1) => diff$1 ?? { action: havePropsChanged(oldProps, news) || bindingDiffs.some((b) => b.action !== "noop") ? "update" : "noop" }), Effect.map((diff$1) => options.force && diff$1.action === "noop" ? { action: "update" } : diff$1));
+		}).pipe(providePlanScope(fqn, oldState.instanceId))).pipe(Effect.map((diff$1) => diff$1 ?? { action: havePropsChanged(oldProps, news) || bindingDiffs.some((b) => b.action !== "noop") ? "update" : "noop" }), Effect.map((diff$1) => options.force && diff$1.action === "noop" ? { action: "update" } : diff$1), Effect.map((diff$1) => forceUpdateAfterAdoption && diff$1.action === "noop" ? { action: "update" } : diff$1));
 		if (oldState.status === "creating") if (diff.action === "noop") return Node({
 			action: "create",
 			props: news,
@@ -1016,7 +1253,7 @@ const make = (stack, options = {}) => Effect.gen(function* () {
 					Binding: void 0,
 					Provider: Provider(resourceType),
 					RemovalPolicy: oldState.removalPolicy,
-					ExecutionContext: void 0,
+					RuntimeContext: void 0,
 					Providers: void 0
 				},
 				downstream: oldDownstreamDependencies[fqn] ?? [],
@@ -1052,73 +1289,6 @@ const providePlanScope = (fqn, instanceId) => (effect) => Effect.serviceOption(A
 var DeleteResourceHasDownstreamDependencies = class extends Data.TaggedError("DeleteResourceHasDownstreamDependencies") {};
 var UnsatisfiedResourceCycle = class extends Data.TaggedError("UnsatisfiedResourceCycle") {};
 
-//#endregion
-//#region lib/Telemetry/Metrics.js
-/**
-* Counter for resource lifecycle operations. Tagged per call with
-* `resource_type`, `op` (`precreate`/`create`/`update`/`delete`/`read`),
-* and `status` (`success`/`error`).
-*/
-const resourceCounter = Metric.counter("alchemy.resource.operations", {
-	description: "Number of resource lifecycle operations dispatched by alchemy apply.",
-	incremental: true
-});
-/**
-* Histogram of how long each lifecycle operation takes.
-*/
-const resourceDuration = Metric.timer("alchemy.resource.duration", { description: "Wall-clock duration of resource lifecycle operations dispatched by alchemy apply." });
-/**
-* Counter for CLI command invocations.
-*/
-const cliCounter = Metric.counter("alchemy.cli.invocations", {
-	description: "Number of alchemy CLI command invocations.",
-	incremental: true
-});
-/**
-* Counter for Cloudflare State Store bootstrap/deploy operations.
-* Tagged per call with `op` (e.g. `deploy`) and `status`
-* (`success`/`error`) so that the deploy success rate of the
-* state store itself can be tracked separately from regular
-* resource lifecycle ops.
-*/
-const stateStoreCounter = Metric.counter("alchemy.state_store.operations", {
-	description: "Number of Cloudflare State Store deploy/bootstrap operations dispatched by alchemy.",
-	incremental: true
-});
-/**
-* Wraps a resource lifecycle Effect to record a counter + timer entry,
-* tagged with `resource_type`, `op`, and `status` (`success`/`error`).
-*
-* Usage:
-* ```ts
-* provider.create(input).pipe(recordResourceOp(node.resource.Type, "create"))
-* ```
-*/
-const recordResourceOp = (resourceType, op) => (self) => Effect.suspend(() => {
-	const startNs = process.hrtime.bigint();
-	const baseAttrs = {
-		resource_type: resourceType,
-		op
-	};
-	return self.pipe(Effect.onExit((exit) => recordOutcome(baseAttrs, Exit.isSuccess(exit) ? "success" : "error", elapsed(startNs))));
-});
-/**
-* Wraps a CLI command Effect to bump {@link cliCounter} with the
-* outcome (`success`/`error`).
-*/
-const recordCli = (command) => (self) => self.pipe(Effect.onExit((exit) => Metric.update(Metric.withAttributes(cliCounter, {
-	command,
-	status: Exit.isSuccess(exit) ? "success" : "error"
-}), 1)));
-const elapsed = (startNs) => Duration.nanos(process.hrtime.bigint() - startNs);
-const recordOutcome = (baseAttrs, status, duration) => {
-	const attrs = {
-		...baseAttrs,
-		status
-	};
-	return Effect.all([Metric.update(Metric.withAttributes(resourceCounter, attrs), 1), Metric.update(Metric.withAttributes(resourceDuration, attrs), duration)], { discard: true });
-};
-
 //#endregion
 //#region lib/Apply.js
 const provideLifecycleScope = (fqn, instanceId) => (effect) => Effect.serviceOption(ArtifactStore).pipe(Effect.map(Option.getOrElse(createArtifactStore)), Effect.flatMap((store) => effect.pipe(Effect.provideService(Artifacts, makeScopedArtifacts(store, fqn)), Effect.provideService(InstanceId, instanceId))));
@@ -1317,12 +1487,13 @@ const executeNode = (fqn, node, tracker, ready, terminalStatuses, session, state
 			const outputs = getOutputs();
 			const news = yield* evaluate(node.props, outputs);
 			const bindingOutputs = excludeDeletedBindings(yield* evaluate(node.bindings, outputs));
-			attr = yield* node.provider.create({
+			attr = yield* node.provider.reconcile({
 				id: logicalId,
 				news,
 				instanceId,
 				bindings: bindingOutputs,
 				session: scopedSession,
+				olds: void 0,
 				output: attr
 			}).pipe(instrumentLifecycle("create", fqn, node.resource.Type, logicalId, instanceId));
 			yield* commit({
@@ -1379,7 +1550,7 @@ const executeNode = (fqn, node, tracker, ready, terminalStatuses, session, state
 			yield* report("updating");
 			const previousProps = node.state.status === "created" || node.state.status === "updated" || node.state.status === "replaced" ? node.state.props : node.state.old.props;
 			const bindingOutputs = excludeDeletedBindings(yield* evaluate(node.bindings, outputs));
-			const attr = yield* node.provider.update({
+			const attr = yield* node.provider.reconcile({
 				id: logicalId,
 				news,
 				instanceId,
@@ -1488,12 +1659,13 @@ const executeNode = (fqn, node, tracker, ready, terminalStatuses, session, state
 			const outputs = getOutputs();
 			const news = yield* evaluate(node.props, outputs);
 			const bindingOutputs = excludeDeletedBindings(yield* evaluate(node.bindings, outputs));
-			attr = yield* node.provider.create({
+			attr = yield* node.provider.reconcile({
 				id: logicalId,
 				news,
 				instanceId,
 				bindings: bindingOutputs,
 				session: scopedSession,
+				olds: void 0,
 				output: attr
 			}).pipe(instrumentLifecycle("create", fqn, node.resource.Type, logicalId, instanceId));
 			yield* commit({
@@ -1569,7 +1741,7 @@ const converge = Effect.fnUntraced(function* (plan, tracker, terminalStatuses, s
 					message: note
 				})
 			};
-			const attr = yield* node.provider.update({
+			const attr = yield* node.provider.reconcile({
 				id: logicalId,
 				news: newProps,
 				instanceId,
@@ -1838,7 +2010,8 @@ const execStack = Effect.fn(function* ({ main, stage: stage$1, envFile: envFile$
 	const stackEffect = yield* importStack(main);
 	const services$1 = Layer.mergeAll(Layer.effect(AlchemyContext, AlchemyContext.asEffect().pipe(Effect.map((ctx) => ({
 		...ctx,
-		dev
+		dev,
+		adopt: adopt$1
 	})))), Layer.succeed(AdoptPolicy, adopt$1), Layer.succeed(ArtifactStore, createArtifactStore()), Layer.succeed(AuthProviders, yield* Effect.serviceOption(AuthProviders).pipe(Effect.map(Option.getOrElse(() => ({}))))), ConfigProvider.layer(withProfileOverride(yield* loadConfigProvider(envFile$1), profile$1)), Logger.layer([fileLogger("out")], { mergeWithExisting: true }), Layer.succeed(Stage, stage$1));
 	yield* Effect.gen(function* () {
 		const cli = yield* Cli;