typekro 0.41.1 → 0.43.0

package/dist/alchemy/resource-registration.js

@@ -24,22 +24,23 @@ import { DEFAULT_DEPLOYMENT_TIMEOUT } from '../core/config/defaults.js';
 import { CEL_EXPRESSION_BRAND } from '../core/constants/brands.js';
 import { ResourceReplacementTimeoutError } from '../core/deployment/errors.js';
 import { isNotFoundError } from '../core/deployment/k8s-helpers.js';
-import { callDeadlineBudget, isRequestTimeoutError, retryOnceOnRequestTimeout, usesExecCredential, withCallDeadline, } from '../core/deployment/poll-timeout.js';
 import { migrateLegacyKroArtifactBindingCrd, repairRetainedKroGeneratedCrdOwnership, } from '../core/deployment/kro-artifact-binding-migration.js';
 import { decideNamespaceOwnershipCreateFirst, deleteNamespaceIfEmpty, HOISTED_NAMESPACES_ANNOTATION, listNamespacesOwnedByRgd, NAMESPACE_OWNER_ANNOTATION, readHoistedNamespacesRecord, } from '../core/deployment/kro-namespace-teardown.js';
+import { callDeadlineBudget, isRequestTimeoutError, retryOnceOnRequestTimeout, usesExecCredential, withCallDeadline, } from '../core/deployment/poll-timeout.js';
 import { SINGLETON_SPEC_FINGERPRINT_ANNOTATION } from '../core/deployment/resource-tagging.js';
 import { materializeSerializableKubeConfigOptions } from '../core/deployment/shared-utilities.js';
 import { singletonDriftVerdict, } from '../core/deployment/singleton-owner-drift.js';
-import { ensureError } from '../core/errors.js';
+import { ensureError, TypeKroError } from '../core/errors.js';
 import { createKubernetesClientProvider } from '../core/kubernetes/client-provider.js';
 import { createBunCompatibleCustomObjectsApi, createBunCompatibleKubernetesObjectApi, } from '../core/kubernetes/index.js';
 import { getComponentLogger } from '../core/logging/index.js';
-import { copyResourceMetadata, getReadinessEvaluator, getResourceScope, setMetadataField, setReadinessEvaluator, setResourceId, } from '../core/metadata/index.js';
+import { copyResourceMetadata, getMetadataField, getReadinessEvaluator, getResourceScope, setMetadataField, setReadinessEvaluator, setResourceId, } from '../core/metadata/index.js';
 import { collectArtifactOutputUses, decodeDirectArtifactExecutionRecord, decodeKroArtifactBundle, materializeDirectArtifactManifest, materializeKroArtifactBundleOperation, planValueSensitiveBindingNames, } from '../core/planning/index.js';
 import { resolvePortableReadinessStrategy } from '../core/readiness/portable-strategies.js';
-import { DirectTypeKroDeployer, KroTypeKroDeployer, ResourceGraphDefinitionDeletionDeferredError, } from './deployers.js';
-import { deleteKroDefinition, deleteKroInstanceFinalizerSafe, decideKroRgdDeletion, } from './kro-delete.js';
 import { setOwnProperty } from '../shared/own-property.js';
+import { DirectTypeKroDeployer, KroTypeKroDeployer, ResourceGraphDefinitionDeletionDeferredError, } from './deployers.js';
+import { decideKroRgdDeletion, deleteKroDefinition, deleteKroInstanceFinalizerSafe, } from './kro-delete.js';
+import { guardKubernetesObjectApi, } from './kubernetes-effect-gate.js';
 /** The single alchemy v2 resource type for any TypeKro KRO resource (RGD or CR instance). */
 export const KRO_RESOURCE_TYPE = 'TypeKro.KroResource';
 /**
@@ -124,78 +125,138 @@ function shouldReplaceKroResourceIdentity(_olds, news, output) {
 }
 /** Test hook for identity-stable replacement decisions with unresolved sibling inputs. */
 export const shouldReplaceKroResourceIdentityForTest = shouldReplaceKroResourceIdentity;
-/**
- * The provider `Layer` that backs {@link KroResource}. Merge into the runtime's providers
- * (alongside the cloud providers) so reconcile/delete run. `reconcile` is the single
- * convergent create/update (apply the manifest, wait for readiness); `delete` performs the
- * finalizer-safe, shared-RGD-aware teardown.
- */
-export const kroProvider = ProviderMod.effect(KroResource, 
-// Typed so the service literal is checked directly against `ProviderService` (methods bivariant) —
-// avoids the exactOptionalPropertyTypes friction of an inferred literal while keeping the effect-hosted
-// registration the conformance boundary requires.
-Effect.succeed({
-    // `namespace` is identity-stable: a namespace change is a replacement, not an in-place update.
-    stables: ['namespace'],
-    // Account-wide enumeration (powers `alchemy nuke`). A generic KRO resource isn't discoverable
-    // cluster-wide from props alone — TypeKro manages teardown through its own `delete` lifecycle —
-    // so this reports nothing to nuke rather than guessing (required by Alchemy's ProviderService).
-    list: () => Effect.succeed([]),
-    diff: Effect.fn(function* ({ olds, news, output }) {
-        if (shouldReplaceKroResourceIdentity(olds, news, output)) {
-            return { action: 'replace' };
-        }
-        return yield* Effect.tryPromise({
-            try: (abortSignal) => detectKroResourceIdentityDrift(olds, output, undefined, abortSignal),
-            catch: ensureError,
-        });
-    }),
-    reconcile: Effect.fn(function* ({ news, output }) {
-        return yield* Effect.tryPromise({
-            try: async (abortSignal) => {
-                const persistedIdentity = persistedKroResourceIdentity(output);
-                const desiredIdentity = desiredKroResourceIdentity(news, output);
-                if (persistedIdentity &&
-                    desiredIdentity &&
-                    desiredIdentity !== UNRESOLVED_IDENTITY &&
-                    !sameKroResourceIdentity(persistedIdentity, desiredIdentity)) {
-                    const previous = propsFromOutput(output);
-                    if (!previous) {
-                        throw new Error(`Alchemy cannot replace prior Kubernetes identity ${persistedIdentity.apiVersion}/${persistedIdentity.kind} ` +
-                            `${persistedIdentity.metadata.namespace ? `${persistedIdentity.metadata.namespace}/` : ''}` +
-                            `${persistedIdentity.metadata.name}: persisted delete properties are unavailable`);
-                    }
-                    await deleteKroResource(previous, abortSignal);
+function hooksForResource(hooks, id) {
+    const beforeEffect = hooks.beforeKubernetesEffect;
+    const guarded = hooks.guardsResource?.(id);
+    if (!beforeEffect && guarded !== true)
+        return hooks;
+    if (guarded === false && hooks.observesResource?.(id) !== true) {
+        const { beforeKubernetesEffect: _unused, ...remaining } = hooks;
+        return remaining;
+    }
+    return {
+        ...hooks,
+        beforeKubernetesEffect: async (props, mutation) => {
+            const decision = await beforeEffect?.call(hooks, props, mutation, { id });
+            if (guarded === true && !decision) {
+                throw new Error(`Guarded resource '${id}' received no Kubernetes effect authority.`);
+            }
+            return decision;
+        },
+    };
+}
+/** Bind operation-scoped Kubernetes effect gates without persisting callback closures in Alchemy state. */
+export function kroProviderWithHooks(hooks = {}) {
+    return ProviderMod.effect(KroResource, 
+    // Typed so the service literal is checked directly against `ProviderService` (methods bivariant) —
+    // avoids the exactOptionalPropertyTypes friction of an inferred literal while keeping the effect-hosted
+    // registration the conformance boundary requires.
+    Effect.succeed({
+        // `namespace` is identity-stable: a namespace change is a replacement, not an in-place update.
+        stables: ['namespace'],
+        // Account-wide enumeration (powers `alchemy nuke`). A generic KRO resource isn't discoverable
+        // cluster-wide from props alone — TypeKro manages teardown through its own `delete` lifecycle —
+        // so this reports nothing to nuke rather than guessing (required by Alchemy's ProviderService).
+        list: () => Effect.succeed([]),
+        diff: Effect.fn(function* ({ id, olds, news, output }) {
+            if (shouldReplaceKroResourceIdentity(olds, news, output)) {
+                // A gated replacement needs reconcile to deploy the new identity
+                // successfully before it deletes the persisted identity. Alchemy's
+                // replace action would run teardown before reconcile can do so.
+                // KRO mode does not use the direct object API gate and keeps
+                // Alchemy's normal create-before-delete replacement behavior.
+                const strategy = typeof news === 'object' && news !== null && 'deploymentStrategy' in news
+                    ? Reflect.get(news, 'deploymentStrategy')
+                    : undefined;
+                if (hooks.beforeKubernetesEffect &&
+                    hooks.guardsResource?.(id) !== false &&
+                    strategy !== 'kro') {
+                    return { action: 'update' };
                 }
-                await waitForPersistedIdentityDeletion(news, output, abortSignal);
-                return deployKroResource(news, abortSignal);
-            },
-            catch: ensureError,
-        });
-    }),
-    delete: Effect.fn(function* ({ output, olds }) {
-        // Prefer the live spec (`olds` — the last-applied props; Alchemy renamed the delete
-        // input's spec field from `news` to `olds`); fall back to reconstructing minimal props from
-        // persisted output (a delete after the spec is gone — e.g. resource removed from the stack).
-        const props = olds ?? propsFromOutput(output);
-        if (props) {
-            yield* Effect.tryPromise({
-                try: (abortSignal) => deleteKroResource(props, abortSignal),
+                return { action: 'replace' };
+            }
+            return yield* Effect.tryPromise({
+                try: (abortSignal) => detectKroResourceIdentityDrift(olds, output, undefined, abortSignal),
                 catch: ensureError,
             });
-        }
-        else {
-            // Neither a live spec nor a usable output (e.g. a create that failed before persisting a
-            // complete output). Warn rather than silently no-op so a possible leaked cluster object is
-            // visible — there's nothing reconstructable to tear down here.
-            getComponentLogger('alchemy-deployment')
-                .child({ alchemyType: KRO_RESOURCE_TYPE })
-                .warn('Skipping delete: no live spec and no reconstructable output to tear down', {
-                hasOutput: !!output,
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output }) {
+            return yield* Effect.tryPromise({
+                try: async (abortSignal) => {
+                    const resourceHooks = hooksForResource(hooks, id);
+                    const persistedIdentity = persistedKroResourceIdentity(output);
+                    const desiredIdentity = desiredKroResourceIdentity(news, output);
+                    const mutationPrecondition = await resourceHooks.beforeReconcile?.(news);
+                    if (resourceHooks.beforeKubernetesEffect && news.deploymentStrategy === 'direct') {
+                        if (mutationPrecondition || news.mutationPrecondition) {
+                            throw new Error('Effect-time Kubernetes admission cannot reuse a preflight mutation precondition.');
+                        }
+                        if (news.deployer) {
+                            throw new Error('Effect-time Kubernetes admission cannot use an injected deployer.');
+                        }
+                    }
+                    if (persistedIdentity &&
+                        desiredIdentity &&
+                        desiredIdentity !== UNRESOLVED_IDENTITY &&
+                        !sameKroResourceIdentity(persistedIdentity, desiredIdentity)) {
+                        const previous = propsFromOutput(output);
+                        if (!previous) {
+                            throw new Error(`Alchemy cannot replace prior Kubernetes identity ${persistedIdentity.apiVersion}/${persistedIdentity.kind} ` +
+                                `${persistedIdentity.metadata.namespace ? `${persistedIdentity.metadata.namespace}/` : ''}` +
+                                `${persistedIdentity.metadata.name}: persisted delete properties are unavailable`);
+                        }
+                        // A distinct guarded identity must exist successfully before the incumbent is
+                        // destroyed. Each write still obtains its own fresh effect-time authority. If
+                        // teardown fails, persisted output stays on the incumbent and retry converges
+                        // against the already-created successor before retrying the old delete.
+                        if (resourceHooks.beforeKubernetesEffect && news.deploymentStrategy === 'direct') {
+                            const successor = await deployKroResource(news, abortSignal, {}, resourceHooks);
+                            await resourceHooks.beforeDelete?.(previous);
+                            await deleteKroResource(previous, abortSignal, resourceHooks);
+                            await waitForPersistedIdentityDeletion(news, output, abortSignal);
+                            return successor;
+                        }
+                        await resourceHooks.beforeDelete?.(previous);
+                        await deleteKroResource(previous, abortSignal, resourceHooks);
+                    }
+                    await waitForPersistedIdentityDeletion(news, output, abortSignal);
+                    return deployKroResource(mutationPrecondition ? { ...news, mutationPrecondition } : news, abortSignal, {}, resourceHooks);
+                },
+                catch: ensureError,
             });
-        }
-    }),
-}));
+        }),
+        delete: Effect.fn(function* ({ id, output, olds }) {
+            // Prefer the live spec (`olds` — the last-applied props; Alchemy renamed the delete
+            // input's spec field from `news` to `olds`); fall back to reconstructing minimal props from
+            // persisted output (a delete after the spec is gone — e.g. resource removed from the stack).
+            const props = yield* Effect.try({
+                try: () => propsForRetainedDelete(olds, output),
+                catch: ensureError,
+            });
+            if (props) {
+                yield* Effect.tryPromise({
+                    try: async (abortSignal) => {
+                        const resourceHooks = hooksForResource(hooks, id);
+                        await resourceHooks.beforeDelete?.(props);
+                        await deleteKroResource(props, abortSignal, resourceHooks);
+                    },
+                    catch: ensureError,
+                });
+            }
+            else {
+                // Neither a live spec nor a usable output (e.g. a create that failed before persisting a
+                // complete output). Warn rather than silently no-op so a possible leaked cluster object is
+                // visible — there's nothing reconstructable to tear down here.
+                getComponentLogger('alchemy-deployment')
+                    .child({ alchemyType: KRO_RESOURCE_TYPE })
+                    .warn('Skipping delete: no live spec and no reconstructable output to tear down', {
+                    hasOutput: !!output,
+                });
+            }
+        }),
+    }));
+}
+export const kroProvider = kroProviderWithHooks();
 /**
  * Instantiate a set of {@link AlchemyResourceDeclaration}s (from a factory's `toAlchemyResources`)
  * as `KroResource`s inside an alchemy Stack, wiring each declaration's `dependsOn` into alchemy
@@ -267,9 +328,9 @@ export function materializeAlchemyResources(kroResource, declarations, options =
             // provider's delete hook. Register it natively so destroy/prune drops
             // only the state entry without invoking Kubernetes deletion. Keep the
             // provider-level retain guard for legacy state and direct provider use.
-            handles[decl.id] = yield* (decl.props.retain === true
+            handles[decl.id] = yield* decl.props.retain === true
                 ? RemovalPolicy.retain()(resource)
-                : resource);
+                : resource;
         }
         return handles;
     });
@@ -322,7 +383,7 @@ function alchemyArtifactOutputs(requirements, uses, options) {
  * Reconcile: deploy a single KRO resource (RGD or CR instance) and return its persisted state.
  * Convergent — alchemy calls this for both create and update; the deployer is idempotent apply.
  */
-async function deployKroResource(props, abortSignal, dependencies = {}) {
+async function deployKroResource(props, abortSignal, dependencies = {}, hooks = {}) {
     abortSignal?.throwIfAborted();
     const logger = getComponentLogger('alchemy-deployment').child({ alchemyType: KRO_RESOURCE_TYPE });
     // Fail-closed PRE-HOIST guard on the ALCHEMY path (finding #7): before applying a
@@ -338,11 +399,11 @@ async function deployKroResource(props, abortSignal, dependencies = {}) {
     abortSignal?.throwIfAborted();
     // finding #2 (adopted-namespace): the hoisted workload Namespace is stamped
     // owned-by-this-RGD at BUILD time (cluster-free). READ the live namespace here and
-    // KEEP that stamp ONLY when typekro actually creates it (404) or already owns it;
+    // KEEP that stamp ONLY after an atomic create succeeds or it already owns it;
     // otherwise strip it so teardown never deletes a namespace typekro merely adopted.
-    const effectiveProps = await _preserveHoistedNamespaceAdoption(props, logger, abortSignal);
+    const effectiveProps = await _preserveHoistedNamespaceAdoption(props, logger, abortSignal, hooks);
     abortSignal?.throwIfAborted();
-    const { deployer, dispose } = await _resolveDeployer(effectiveProps, 'deployment', abortSignal);
+    const { deployer, dispose } = await _resolveDeployer(effectiveProps, 'deployment', abortSignal, hooks);
     try {
         // Direct mode: hand the deployer the live state of this resource's dependencies so the engine
         // resolves its cross-resource references + CEL expressions against them (the deps deployed
@@ -387,6 +448,7 @@ async function deployKroResource(props, abortSignal, dependencies = {}) {
             copyResourceMetadata(resourceForDeploy, wrapped);
             resourceForDeploy = wrapped;
         }
+        resourceForDeploy = applyKroResourceMutationPrecondition(resourceForDeploy, effectiveProps.mutationPrecondition);
         if (effectiveProps.deploymentStrategy === 'kro' &&
             resourceForDeploy.kind === 'ResourceGraphDefinition') {
             await (dependencies.migrateLegacyArtifactBindings ?? migrateLegacyKroArtifactBindingCrd)(dependencies.kubeConfigForMigration?.() ??
@@ -424,6 +486,39 @@ async function deployKroResource(props, abortSignal, dependencies = {}) {
  * through the Effect provider above.
  */
 export const deployKroResourceForTest = deployKroResource;
+function applyKroResourceMutationPrecondition(resource, precondition) {
+    if (!precondition)
+        return resource;
+    const guarded = {
+        ...resource,
+        metadata: { ...(resource.metadata ?? { name: '' }) },
+    };
+    copyResourceMetadata(resource, guarded);
+    if (precondition.operation === 'create') {
+        setMetadataField(guarded, 'applyPolicy', {
+            strategy: 'create-only',
+        });
+        return guarded;
+    }
+    const policy = getMetadataField(guarded, 'applyPolicy');
+    if (policy?.strategy === 'replace' ||
+        policy?.existingResource === 'replace' ||
+        policy?.immutableFieldPolicy === 'recreate') {
+        throw new TypeKroError(`A preconditioned update cannot use replacement semantics for ${guarded.kind}/${guarded.metadata?.name}`, 'MUTATION_PRECONDITION_REPLACEMENT_UNSAFE');
+    }
+    const updated = {
+        ...guarded,
+        metadata: {
+            ...(guarded.metadata ?? { name: '' }),
+            uid: precondition.uid,
+            resourceVersion: precondition.resourceVersion,
+        },
+    };
+    copyResourceMetadata(guarded, updated);
+    return updated;
+}
+/** @internal Exact helper shared with focused operation-host tests. */
+export const applyKroResourceMutationPreconditionForTest = applyKroResourceMutationPrecondition;
 function persistedKroResourceIdentity(output) {
     const prior = output?.deployedResource;
     if (!prior)
@@ -789,14 +884,46 @@ export const existingInstanceNamespacesAlchemyForTest = _existingInstanceNamespa
  * Returns props unchanged for non-hoisted-namespace resources or when the stamp should
  * stay; otherwise a shallow copy whose resource has the ownership annotation removed.
  */
-async function _preserveHoistedNamespaceAdoption(props, logger, abortSignal) {
+async function _preserveHoistedNamespaceAdoption(props, logger, abortSignal, hooks = {}) {
     if (props.namespaceEmptyGate !== true || props.namespaceOwnerRgd === undefined)
         return props;
+    const namespaceOwnerRgd = props.namespaceOwnerRgd;
+    if (props.resource.kind !== 'Namespace') {
+        throw new Error('Hoisted namespace ownership requires a Namespace resource.');
+    }
+    // This explicit hoisted role is cluster-scoped even after legacy Alchemy input serialization
+    // loses factory WeakMap metadata. Preserve it through adoption copies and subsequent apply.
+    const namespaceResource = { ...props.resource, scope: 'cluster' };
+    copyResourceMetadata(props.resource, namespaceResource);
+    setMetadataField(namespaceResource, 'scope', 'cluster');
+    props = { ...props, resource: namespaceResource };
     const name = props.resource.metadata?.name;
     if (typeof name !== 'string' || name.length === 0)
         return props;
     const kc = _createClientProvider(props, 'ownership-check');
-    const api = _boundClusterCalls(createBunCompatibleKubernetesObjectApi(kc, props.options?.httpTimeouts), props, 'ownership-check', abortSignal, kc);
+    const boundedApi = _boundClusterCalls(createBunCompatibleKubernetesObjectApi(kc, props.options?.httpTimeouts), props, 'ownership-check', abortSignal, kc);
+    const effectGate = hooks.beforeKubernetesEffect;
+    const guarded = effectGate && props.deploymentStrategy === 'direct';
+    const api = guarded
+        ? guardKubernetesObjectApi(boundedApi, (mutation) => effectGate(props, mutation))
+        : boundedApi;
+    // Existing namespaces require no ownership-create attempt: keep only an already-present
+    // matching stamp. Absence never grants ownership; the admitted atomic create below does.
+    // A race still receives the established helper's 409/read/adopt decision.
+    let existingNamespace;
+    if (guarded) {
+        try {
+            existingNamespace = await api.read({
+                apiVersion: 'v1',
+                kind: 'Namespace',
+                metadata: { name },
+            });
+        }
+        catch (error) {
+            if (!isNotFoundError(error))
+                throw error;
+        }
+    }
     // CREATE-FIRST ownership (finding #3), matching the imperative path: attempt to CREATE
     // the namespace WITH the build-time stamp. A 201 is atomic proof typekro created it
     // (owned). A 409 means it already exists — owned ONLY if a prior create by this RGD
@@ -806,17 +933,22 @@ async function _preserveHoistedNamespaceAdoption(props, logger, abortSignal) {
     // (idempotent), so a 201 here is not the final apply — it is the ownership PROBE.
     let ownsNamespace;
     try {
-        const decision = await decideNamespaceOwnershipCreateFirst(api, props.resource, props.namespaceOwnerRgd);
-        ownsNamespace = decision.owned;
+        ownsNamespace = existingNamespace
+            ? existingNamespace.metadata?.annotations?.[NAMESPACE_OWNER_ANNOTATION] === namespaceOwnerRgd
+            : (await decideNamespaceOwnershipCreateFirst(api, props.resource, namespaceOwnerRgd)).owned;
     }
     catch (error) {
+        // Guarded admission/API failures terminate this operation, never fall through to a
+        // differently shaped apply or consume another permit after a rejected preparation write.
+        if (guarded)
+            throw error;
         // A non-conflict CREATE failure (or a failed conflict-read) — do NOT claim ownership
         // (conservative: a namespace we cannot provably create/own must not be stampable, or
         // teardown might delete an adopted one). The deployer's SSA apply below surfaces the
         // real error if the cluster is genuinely broken.
         logger.debug('Create-first ownership probe failed; treating as adopted (alchemy)', {
             namespace: name,
-            rgd: props.namespaceOwnerRgd,
+            rgd: namespaceOwnerRgd,
             error: ensureError(error).message,
         });
         ownsNamespace = false;
@@ -825,7 +957,7 @@ async function _preserveHoistedNamespaceAdoption(props, logger, abortSignal) {
         return props; // keep the build-time ownership stamp
     logger.debug('Preserving namespace adoption — stripping build-time ownership stamp (alchemy)', {
         namespace: name,
-        rgd: props.namespaceOwnerRgd,
+        rgd: namespaceOwnerRgd,
     });
     return { ...props, resource: _stripNamespaceOwnerAnnotation(props.resource) };
 }
@@ -1093,7 +1225,7 @@ function _resourceFromDirectArtifactRecord(props, preserveSensitiveInputs = fals
         return [binding, preserveSensitiveInputs ? value : Redacted.value(value)];
     }));
     const artifactOutputs = artifactOutputsForOperation(record.artifact, props, preserveSensitiveInputs, `Direct artifact ${logicalId}`);
-    return materializeDirectArtifactManifest(record.artifact, {
+    const resource = materializeDirectArtifactManifest(record.artifact, {
         instanceName: props.resourceId ?? logicalId,
         runtimeResources: { [logicalId]: props.resource },
         ...(Object.keys(sensitive).length > 0 ? { sensitive } : {}),
@@ -1101,6 +1233,17 @@ function _resourceFromDirectArtifactRecord(props, preserveSensitiveInputs = fals
         ...(readinessEvaluators ? { readinessEvaluators } : {}),
         resolveReadinessStrategy: resolvePortableReadinessStrategy,
     }, props.resourceId ?? logicalId);
+    const externalReferences = (record.externalReferences ?? []).map((reference) => {
+        const id = reference.sourceNodeId ?? reference.id;
+        return {
+            id,
+            manifest: materializeDirectArtifactManifest(reference, { instanceName: props.resourceId ?? logicalId }, id),
+        };
+    });
+    if (externalReferences.length > 0) {
+        setMetadataField(resource, 'directExternalReferences', externalReferences);
+    }
+    return resource;
 }
 /** Internal test hook for canonical direct-artifact state rehydration. */
 export const resourceFromDirectArtifactRecordForTest = _resourceFromDirectArtifactRecord;
@@ -1178,6 +1321,35 @@ function propsFromOutput(output) {
         ...(output.namespaceOwnerRgd !== undefined && { namespaceOwnerRgd: output.namespaceOwnerRgd }),
     };
 }
+/** Recover a retained base-format input's scope only from its matching persisted output. */
+function propsForRetainedDelete(olds, output) {
+    if (!olds)
+        return propsFromOutput(output);
+    const outputScope = output?.resource && getResourceScope(output.resource);
+    if (!outputScope)
+        return olds;
+    const deployed = persistedKroResourceIdentity(output);
+    const sameIdentity = (left, right) => left.apiVersion === right.apiVersion &&
+        left.kind === right.kind &&
+        left.metadata?.name === right.metadata?.name &&
+        left.metadata?.namespace === right.metadata?.namespace;
+    if (!deployed ||
+        !sameIdentity(olds.resource, output.resource) ||
+        !sameIdentity(output.resource, deployed)) {
+        throw new Error('Retained Alchemy delete scope cannot be recovered from a conflicting persisted Kubernetes identity.');
+    }
+    const oldScope = getResourceScope(olds.resource);
+    if (oldScope && oldScope !== outputScope) {
+        throw new Error('Retained Alchemy delete scope conflicts with the persisted Kubernetes output.');
+    }
+    if (oldScope)
+        return olds;
+    const resource = { ...olds.resource, scope: outputScope };
+    copyResourceMetadata(olds.resource, resource);
+    return { ...olds, resource };
+}
+/** @internal Retained-state migration regression helper. */
+export const propsForRetainedDeleteForTest = propsForRetainedDelete;
 /**
  * Create KubernetesClientProvider using centralized configuration management
  * Eliminates complex multi-stage fallback logic and consolidates TLS handling
@@ -1208,7 +1380,7 @@ function _createClientProvider(props, phase) {
 /**
  * Create the appropriate deployer based on the deployment strategy
  */
-async function _createDeployer(kc, props, abortSignal) {
+async function _createDeployer(kc, props, abortSignal, hooks = {}) {
     // Use dynamic import to avoid circular dependencies
     const { DirectDeploymentEngine } = await import('../core/deployment/engine.js');
     const { DeploymentMode } = await import('../core/references/index.js');
@@ -1221,7 +1393,12 @@ async function _createDeployer(kc, props, abortSignal) {
     // config is still passed so Bun applies it at the socket (which can also cancel the request),
     // and the deadline wrapper adds the runtime-neutral bound on top. Both use the same per-verb
     // budgets, so under Bun this changes nothing.
-    const engine = new DirectDeploymentEngine(kc, _boundClusterCalls(createBunCompatibleKubernetesObjectApi(kc, props.options?.httpTimeouts), props, 'deployment-engine', abortSignal, kc), undefined, DeploymentMode.DIRECT, props.options?.httpTimeouts);
+    const boundedApi = _boundClusterCalls(createBunCompatibleKubernetesObjectApi(kc, props.options?.httpTimeouts), props, 'deployment-engine', abortSignal, kc);
+    const effectGate = hooks.beforeKubernetesEffect;
+    const api = effectGate && props.deploymentStrategy === 'direct'
+        ? guardKubernetesObjectApi(boundedApi, (mutation) => effectGate(props, mutation))
+        : boundedApi;
+    const engine = new DirectDeploymentEngine(kc, api, undefined, DeploymentMode.DIRECT, props.options?.httpTimeouts);
     if (props.deploymentStrategy === 'direct') {
         return new DirectTypeKroDeployer(engine);
     }
@@ -1343,12 +1520,15 @@ function enrichKroDeletionOptions(props, options) {
 /** Internal test hook for legacy Alchemy KRO state rehydration. */
 export const inferKroDeletionOptionsForTest = inferKroDeletionOptions;
 export const enrichKroDeletionOptionsForTest = enrichKroDeletionOptions;
-async function _resolveDeployer(props, phase, abortSignal) {
+async function _resolveDeployer(props, phase, abortSignal, hooks = {}) {
     if (props.deployer) {
+        if (hooks.beforeKubernetesEffect && props.deploymentStrategy === 'direct') {
+            throw new Error('Effect-time Kubernetes admission cannot use an injected deployer.');
+        }
         return { deployer: props.deployer, dispose: async () => { } };
     }
     const kc = _createClientProvider(props, phase);
-    const deployer = await _createDeployer(kc, props, abortSignal);
+    const deployer = await _createDeployer(kc, props, abortSignal, hooks);
     return {
         deployer,
         dispose: async () => {
@@ -1363,7 +1543,7 @@ async function _resolveDeployer(props, phase, abortSignal) {
  * stacks' instances reference), we log and let alchemy drop the state entry — the orphaned
  * RGD is cluster-scoped and dies with the cluster; it must not wedge the destroy.
  */
-async function deleteKroResource(props, abortSignal) {
+async function deleteKroResource(props, abortSignal, hooks = {}) {
     abortSignal?.throwIfAborted();
     const logger = getComponentLogger('alchemy-deployment').child({ alchemyType: KRO_RESOURCE_TYPE });
     // Retained (shared) resources — e.g. the KRO instance control-plane Namespace —
@@ -1396,9 +1576,15 @@ async function deleteKroResource(props, abortSignal) {
             return;
         }
         const kubeConfig = _createClientProvider(props, 'delete');
+        const effectGate = hooks.beforeKubernetesEffect;
+        const k8sApi = effectGate && props.deploymentStrategy === 'direct'
+            ? guardKubernetesObjectApi(createBunCompatibleKubernetesObjectApi(kubeConfig), (mutation) => effectGate(props, mutation))
+            : undefined;
         abortSignal?.throwIfAborted();
         await deleteNamespaceIfEmpty(kubeConfig, namespaceName, {
             logger,
+            ...(k8sApi ? { k8sApi } : {}),
+            ...(k8sApi ? { forbidResidualPvcCleanup: true } : {}),
             // Ownership record (finding #4) + gated delete (finding #1): only delete a
             // namespace this composition's RGD created, and gate it to a real 404.
             ...(props.namespaceOwnerRgd !== undefined && { ownedByRgd: props.namespaceOwnerRgd }),
@@ -1415,7 +1601,7 @@ async function deleteKroResource(props, abortSignal) {
         abortSignal?.throwIfAborted();
         return;
     }
-    const { deployer, dispose } = await _resolveDeployer(props, 'delete', abortSignal);
+    const { deployer, dispose } = await _resolveDeployer(props, 'delete', abortSignal, hooks);
     try {
         await deployer.delete(props.resource, {
             mode: props.deploymentStrategy,