@orchestraworks/cli 0.5.7 → 0.6.0

package/dist/engine/gateway-key-reconcile.js

@@ -13,17 +13,17 @@
 import { gatewayKeyRefOf } from "../core/gateway-key-recipe.js";
 import { refToken } from "../core/tokens.js";
 import { credentialValueWritten, driftedFields, failing, getBySlugOrUndefined, pushOutcome, stampTeam, } from "./apply-core.js";
-import { PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY, refuseIf } from "./refusals.js";
+import { refuseIf } from "./refusals.js";
 import { httpStatusOf } from "./client.js";
 import { PreflightError } from "./preflight.js";
-import { createLabels, labelsPatch, MANAGED_BY_LABEL_KEY } from "../core/labels.js";
-import { declaredSecretHosts, metadataHostsChange, metadataInjectionChange, pendingSecretWrite, reconcileInjection, } from "./secrets-apply.js";
+import { createLabels, labelsPatch, MANAGED_BY_LABEL_KEY, oldMarkersCleared, oldMarkersMoved, PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY, readMarker, } from "../core/labels.js";
+import { declaredSecretInjection, metadataInjectionChange, pendingSecretWrite, reconcileInjection, } from "./secrets-apply.js";
 /**
  * The reserved marker rides the ordinary labels wire field — never smuggled into the write-only value or a
  * second column — and is removed by the final token PATCH. It lives in a leaf module because the aggregate
  * refusal classifier's rotation message names it too.
  */
-export { PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY } from "./refusals.js";
+export { PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY } from "../core/labels.js";
 /**
  * The platform requires a non-empty `value` on create and the token does not exist yet, so a reservation
  * writes this inert literal and the final PATCH replaces it. The Secret is detectably pending for exactly as
@@ -149,14 +149,17 @@ async function applySteadyGatewayKey(decision, apis, outcomes, applied) {
         action = "updated";
     }
     pushOutcome(outcomes, applied, decision.resource, live.id, action);
-    // The paired Secret needs no value write in steady state, but a recipe or hosts edit still reconciles
+    // The paired Secret needs no value write in steady state, but a recipe edit, its hosts included, still reconciles
     // through a value-less PATCH — exactly what `applySecrets` would have done had this lane not owned it.
     const liveSecret = decision.liveSecret;
     const injectionChange = metadataInjectionChange(secretInjection(decision.secretResource), liveSecret.injection);
-    const hostsChange = metadataHostsChange(declaredSecretHosts(decision.secretResource.payload), liveSecret.hosts);
+    const labelsMove = oldMarkersMoved(liveSecret.labels);
     let secretAction = "unchanged";
-    if (injectionChange !== undefined || hostsChange !== undefined) {
-        const body = { ...injectionChange, ...hostsChange };
+    if (injectionChange !== undefined || labelsMove !== undefined) {
+        const body = {
+            ...injectionChange,
+            ...(labelsMove !== undefined ? { labels: labelsMove } : {}),
+        };
         await failing(() => apis.secrets.updateSecret({ id: liveSecret.id, updateSecretRequest: body }), { kind: "secret", slug: decision.secretSlug, op: "update" }, outcomes);
         secretAction = "updated";
     }
@@ -174,9 +177,12 @@ async function mintGatewayKey(decision, apis, outcomes, applied, tokens, factory
     const refKey = refToken("gateway-key", decision.resource.path.split("/"));
     // The FINAL patch removes the pending marker and stamps ownership; the merge keeps every caller-authored entry
     // an adopted Secret carries.
-    const finalLabels = { [MANAGED_BY_LABEL_KEY]: factory, [PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY]: null };
+    const finalLabels = {
+        [MANAGED_BY_LABEL_KEY]: factory,
+        [PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY]: null,
+        ...oldMarkersCleared(decision.liveSecret?.labels),
+    };
     const declaredInjection = secretInjection(decision.secretResource);
-    const declaredHosts = declaredSecretHosts(decision.secretResource.payload);
     // (1) Make the paired Secret detectably pending BEFORE the mint.
     let secretId;
     if (decision.action === "mint-new") {
@@ -188,7 +194,6 @@ async function mintGatewayKey(decision, apis, outcomes, applied, tokens, factory
             labels: { [PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY]: decision.slug },
             ...placement,
             ...(declaredInjection !== undefined ? { injection: declaredInjection } : {}),
-            ...(declaredHosts !== undefined ? { hosts: declaredHosts } : {}),
         };
         const created = await failing(() => apis.secrets.createSecret({ createSecretRequest: createBody }), { kind: "secret", slug: decision.secretSlug, op: "create" }, outcomes);
         secretId = created.id;
@@ -202,6 +207,7 @@ async function mintGatewayKey(decision, apis, outcomes, applied, tokens, factory
             await patchSecretPendingMarker(apis, outcomes, decision.secretSlug, secretId, {
                 [MANAGED_BY_LABEL_KEY]: factory,
                 [PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY]: decision.slug,
+                ...oldMarkersCleared(liveSecret.labels),
             });
         }
     }
@@ -237,8 +243,6 @@ async function mintGatewayKey(decision, apis, outcomes, applied, tokens, factory
             // No team: a `mint-new` reservation already placed the create, and an adopted or resumed Secret is
             // only here because the decide phase found it already in the declared team.
             ...(injection !== undefined ? { injection } : {}),
-            // A `mint-new` reservation already carried the hosts on its create.
-            ...(decision.action !== "mint-new" && declaredHosts !== undefined ? { hosts: declaredHosts } : {}),
         },
     }), { kind: "secret", slug: decision.secretSlug, op: "update" }, outcomes);
     // The pinned asymmetry between the pair's two rows: the `gateway-key` row is the MINT, whose sensitivity
@@ -277,7 +281,7 @@ function pairedSecretResource(plan, key) {
     return paired[0];
 }
 function hasPendingMarker(secret) {
-    return secret.labels?.[PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY] !== undefined;
+    return readMarker(secret.labels, PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY) !== undefined;
 }
 /**
  * Exactly the fields the update request accepts and the construct emits. `monthlyCreditCap` is present only
@@ -293,5 +297,5 @@ function declaredKeyState(payload) {
     };
 }
 function secretInjection(secretResource) {
-    return secretResource.payload.injection;
+    return declaredSecretInjection(secretResource.payload);
 }

package/dist/engine/pipeline-reconcile.js

@@ -11,7 +11,7 @@
 import { OPEN_CATEGORIES } from "../constructs/pipeline.js";
 import { resolveConditionReferences, resolveStageInField } from "./condition-references.js";
 import { wireNode } from "../constructs/workflow-filter.js";
-import { createLabels, labelsPatch, MANAGED_BY_LABEL_KEY } from "../core/labels.js";
+import { createLabels, labelsPatch, managedByOf } from "../core/labels.js";
 import { refToken } from "../core/tokens.js";
 import { exactDeepEqual, failing, getBySlugOrUndefined, stampTeam, } from "./apply-core.js";
 import { PreflightError } from "./preflight-errors.js";
@@ -242,7 +242,7 @@ export async function workflowStagesAfterApply(pipeline, live, resources, factor
         const versions = [
             ...declaredEntries.filter((entry) => refs.has(entry.workflow)).map((entry) => entry.version),
             ...liveEntries
-                .filter((entry) => entry.labels[MANAGED_BY_LABEL_KEY] !== factory && refs.has(entry.workflow.id))
+                .filter((entry) => managedByOf(entry.labels) !== factory && refs.has(entry.workflow.id))
                 .map((entry) => entry.version ?? null),
         ];
         if (versions.some((version) => typeof version === "number"))

package/dist/engine/pipeline-workflow-reconcile.js

@@ -1,4 +1,4 @@
-// A pipeline's workflow entries. Apply owns only the entries it stamped with this factory's `sfdk.managedBy`:
+// A pipeline's workflow entries. Apply owns only the entries it stamped with this factory's managed-by marker:
 // each declared entry takes a stamped live entry of its workflow, an identical one first and then the next in
 // order, and a changed one is patched field by field; a declared entry left over is added with the stamp, and
 // a stamped entry nothing declares is removed. Every other entry stays where it is and is named, since an
@@ -9,11 +9,11 @@
 // new rules before its entry says so; the entries phase then sets each to its declared version.
 import { APPLIED_VERSION } from "../constructs/pipeline.js";
 import { wireNode } from "../constructs/workflow-filter.js";
-import { MANAGED_BY_LABEL_KEY } from "../core/labels.js";
+import { MANAGED_BY_LABEL_KEY, managedByOf, oldMarkersCleared } from "../core/labels.js";
 import { exactDeepEqual, failing, getBySlugOrUndefined } from "./apply-core.js";
 import { rawJsonBody } from "./raw-json-request.js";
 export function entryChange(declared, live, factory) {
-    const stamped = live.filter((entry) => entry.labels[MANAGED_BY_LABEL_KEY] === factory);
+    const stamped = live.filter((entry) => managedByOf(entry.labels) === factory);
     const taken = new Set();
     const take = (entry, fits) => {
         const found = stamped.find((candidate) => !taken.has(candidate.id) && names(entry, candidate) && fits(candidate));
@@ -21,18 +21,18 @@ export function entryChange(declared, live, factory) {
             taken.add(found.id);
         return found;
     };
-    const exact = declared.map((entry) => take(entry, (candidate) => patchOf(entry, candidate) === undefined));
+    const exact = declared.map((entry) => take(entry, (candidate) => patchOf(entry, candidate, factory) === undefined));
     const matched = declared.map((entry, index) => exact[index] ?? take(entry, () => true));
     return {
         declared: declared.map((entry, index) => ({ entry, ...(matched[index] ? { liveId: matched[index].id } : {}) })),
         create: declared.filter((_, index) => matched[index] === undefined),
         update: declared.flatMap((entry, index) => {
             const live = matched[index];
-            const patch = live !== undefined ? patchOf(entry, live) : undefined;
+            const patch = live !== undefined ? patchOf(entry, live, factory) : undefined;
             return live !== undefined && patch !== undefined ? [{ id: live.id, patch }] : [];
         }),
         remove: stamped.filter((entry) => !taken.has(entry.id)),
-        unmanaged: live.filter((entry) => entry.labels[MANAGED_BY_LABEL_KEY] !== factory),
+        unmanaged: live.filter((entry) => managedByOf(entry.labels) !== factory),
     };
 }
 export function entriesUnchanged(change) {
@@ -87,7 +87,7 @@ export async function applyEntriesPhase(apis, pipelines, versions, factory, outc
  */
 export async function pinFollowingEntries(apis, pipeline, workflow, version, factory) {
     const live = await getBySlugOrUndefined(() => apis.pipelines.getPipeline({ id: pipeline }));
-    const following = (live?.workflows ?? []).filter((entry) => entry.labels[MANAGED_BY_LABEL_KEY] === factory && entry.workflow.id === workflow.id && entry.version === undefined);
+    const following = (live?.workflows ?? []).filter((entry) => managedByOf(entry.labels) === factory && entry.workflow.id === workflow.id && entry.version === undefined);
     for (const entry of following)
         await patchEntry(apis, live.id, entry.id, { version });
     return following.length;
@@ -165,9 +165,15 @@ export function describeOverlaps(proposedList, overlaps) {
 function names(entry, live) {
     return entry.workflow === live.workflow.slug || entry.workflow === live.workflow.id;
 }
-/** The fields a patch must send to make [live] the declared entry, null resetting; `undefined` when none. */
-function patchOf(entry, live) {
+/**
+ * The fields a patch must send to make [live] the declared entry, null resetting; `undefined` when none. An entry
+ * stamped under the old prefix has its stamp moved.
+ */
+function patchOf(entry, live, factory) {
     const patch = {};
+    const moved = oldMarkersCleared(live.labels);
+    if (Object.keys(moved).length > 0)
+        patch.labels = { ...moved, [MANAGED_BY_LABEL_KEY]: factory };
     if (entry.version !== (live.version ?? null))
         patch.version = entry.version;
     const where = entry.where === null ? null : wireNode(entry.where);

package/dist/engine/reconcile.js

@@ -6,7 +6,7 @@
 import { CONNECTOR_SECRET_WIRE_FIELDS, connectorImmutableFields, } from "../constructs/connector.js";
 import { isEnvImportMarker, parseEnvImportMarker } from "../constructs/references.js";
 import { isGatewayKeyRecipe } from "../core/gateway-key-recipe.js";
-import { createLabels, labelsPatch, MANAGED_BY_LABEL_KEY, stampManagedBy } from "../core/labels.js";
+import { createLabels, labelsPatch, MANAGED_BY_LABEL_KEY, oldMarkersMoved, stampManagedBy } from "../core/labels.js";
 import { isRefToken, parseRefToken, refToken } from "../core/tokens.js";
 import { ApplyError, credentialValueWritten, defaultPrint, createTeamResolver, describeTargetOrganization, failing, getBySlugOrUndefined, modelSettingsUnchanged, stampTeam, standbyCapacityUnchanged, subsetDeepEqual, } from "./apply-core.js";
 import { preApprovalLevers, typedAtTerminalRemedy, } from "../cli/core/approval-policy.js";
@@ -22,7 +22,7 @@ import { applyCeremonyBackedConnection, isCeremonyBackedConnection, } from "./co
 import { assertManagedChatConnectionForDesired } from "./connection-readiness.js";
 import { removedConfigurationNotice } from "./connector-configuration.js";
 import { PreflightError, PreflightRefusalError, readConnection, RedactedRefError, reservedProviderSecretIds, resolveSecretRef, validateConnectionImport, validateRefShape, } from "./preflight.js";
-import { allRootSourceLabels, commandLineOccurrencesFor, containsCommandLineRecipe, declaredSecretHosts, decideSecretWrite, metadataHostsChange, metadataInjectionChange, pendingSecretWrite, reconcileInjection, replacesLiveCredentialValue, resolveSecretValueSource, } from "./secrets-apply.js";
+import { allRootSourceLabels, commandLineOccurrencesFor, containsCommandLineRecipe, declaredSecretInjection, decideSecretWrite, metadataInjectionChange, pendingSecretWrite, reconcileInjection, replacesLiveCredentialValue, resolveSecretValueSource, } from "./secrets-apply.js";
 import { collectCommandLineValues, } from "./command-line-values.js";
 // These live in the leaf module `engine/apply-core.ts` so the per-kind reconcile lanes can share them
 // without importing this monolith, which imports THEM — a cycle. Re-exported here so `engine/reconcile`
@@ -185,7 +185,7 @@ export async function reconcile(plan, apis, opts, appliedOut) {
                     await applyComputeProvider(resource, apis, outcomes, applied, opts.onComputeProviderKey);
                     break;
                 case "environment":
-                    await applyEnvironment(resource, apis, outcomes, applied, reserved, teams);
+                    await applyEnvironment(resource, apis, outcomes, applied, connections, reserved, teams);
                     break;
                 case "skill":
                     await applySkill(resource, apis, outcomes, applied, teams);
@@ -376,14 +376,14 @@ async function applySecrets(plan, apis, opts, env, outcomes, applied, teams, gat
             ? undefined
             : resolveSecretValueSource(resource.valueFrom, env);
         // Diffed against the live recipe so a value-less recipe edit still PATCHes instead of silently no-oping.
-        const desiredInjection = resource.payload.injection;
-        const injectionChange = metadataInjectionChange(desiredInjection, live?.injection);
-        const hostsChange = metadataHostsChange(declaredSecretHosts(resource.payload), live?.hosts);
+        const injectionChange = metadataInjectionChange(declaredSecretInjection(resource.payload), live?.injection);
+        // A marker an apply before the rename stamped moves to the new prefix even when nothing else changes.
+        const labelsMove = oldMarkersMoved(live?.labels);
         const decision = decideSecretWrite(resolvedValue, live !== undefined, {
             slug,
             envName,
             injectionChange,
-            hostsChange,
+            ...(labelsMove !== undefined ? { labelsChange: { labels: labelsMove } } : {}),
             commandLinePending,
         });
         if (decision.kind === "skip-empty") {
@@ -399,6 +399,7 @@ async function applySecrets(plan, apis, opts, env, outcomes, applied, teams, gat
             value: resolvedValue,
             id: live?.id,
             liveInjection: live?.injection,
+            labelsMove,
             replacesLiveValue: replacesLiveCredentialValue(resource.valueFrom, decision.kind === "overwrite" ? "overwrite" : "create"),
         });
     }
@@ -481,8 +482,7 @@ async function applySecrets(plan, apis, opts, env, outcomes, applied, teams, gat
     }
     // Write phase — creates and overwrites, in plan order.
     for (const p of secretPlans) {
-        const desiredInjection = p.resource.payload.injection;
-        const desiredHosts = declaredSecretHosts(p.resource.payload);
+        const desiredInjection = declaredSecretInjection(p.resource.payload);
         if (p.decision.kind === "create") {
             const placement = {};
             stampTeam(placement, p.team);
@@ -498,7 +498,6 @@ async function applySecrets(plan, apis, opts, env, outcomes, applied, teams, gat
                 ...placement,
                 // Live is absent, so never a `null` clear here.
                 ...(desiredInjection !== undefined ? { injection: desiredInjection } : {}),
-                ...(desiredHosts !== undefined ? { hosts: desiredHosts } : {}),
             };
             const created = await failing(() => apis.secrets.createSecret({ createSecretRequest: body }), { kind: "secret", slug: p.slug, op: "create" }, outcomes);
             p.id = created.id;
@@ -513,16 +512,16 @@ async function applySecrets(plan, apis, opts, env, outcomes, applied, teams, gat
                 description: p.resource.payload.description,
                 value: p.value,
                 ...(injection !== undefined ? { injection } : {}),
-                ...(desiredHosts !== undefined ? { hosts: desiredHosts } : {}),
+                ...(p.labelsMove !== undefined ? { labels: p.labelsMove } : {}),
             };
             await failing(() => apis.secrets.updateSecret({ id: p.id, updateSecretRequest: body }), { kind: "secret", slug: p.slug, op: "update" }, outcomes);
         }
         else if (p.decision.kind === "metadata-update") {
-            // The secret exists with no fresh value but its recipe or hosts changed: a value-less PATCH carrying
-            // only the changed fields.
+            // The secret exists with no fresh value but its recipe changed or an old marker moves: a value-less PATCH
+            // carrying the recipe and the label move alone.
             const body = {
                 ...(p.decision.injection !== undefined ? { injection: p.decision.injection } : {}),
-                ...(p.decision.hosts !== undefined ? { hosts: p.decision.hosts } : {}),
+                ...(p.decision.labels !== undefined ? { labels: p.decision.labels } : {}),
             };
             await failing(() => apis.secrets.updateSecret({ id: p.id, updateSecretRequest: body }), { kind: "secret", slug: p.slug, op: "update" }, outcomes);
         }
@@ -839,7 +838,26 @@ function connectionExpectFor(imports, ref) {
     }
     return { provider, install: Object.keys(install).length > 0 ? install : undefined };
 }
-async function applyEnvironment(resource, apis, outcomes, applied, reserved, teams) {
+/** The prefix an env value carries before a credential reference, which the egress edge reads. */
+const ENV_REFERENCE_PREFIX = "orchestra:";
+const CREDENTIAL_REFERENCE = /^(secret|connection)\/(.+)$/;
+/**
+ * `secret/<ref>` or `connection/<ref>` with its ref, a reference token or an import as written, resolved to
+ * the live id: the edge and the platform read an exact id, never a slug. Text naming neither is left as it is.
+ */
+async function resolveCredentialReference(text, label, apis, applied, connections) {
+    const match = CREDENTIAL_REFERENCE.exec(text);
+    if (match === null)
+        return text;
+    const [, kind, ref] = match;
+    if (kind === "connection")
+        return `connection/${await connections.resolve(ref)}`;
+    if (isRefToken(ref))
+        return `secret/${resolveManagedToken(ref, applied)}`;
+    validateRefShape(ref, label);
+    return `secret/${(await resolveSecretRef(apis, { value: ref, sourceLabel: label })).id}`;
+}
+async function applyEnvironment(resource, apis, outcomes, applied, connections, reserved, teams) {
     const body = clonePayload(resource.payload);
     const team = await teams.desired(body.teamId, { kind: "environment", slug: resource.slug, op: "get" }, outcomes);
     stampTeam(body, team);
@@ -884,6 +902,21 @@ async function applyEnvironment(resource, apis, outcomes, applied, reserved, tea
             reservedProviderSecretIds: await reserved(),
         }, outcomes);
     }
+    // Each credential an env value or a default names becomes its id before anything is written.
+    const env = (launchSpec.env ?? {});
+    for (const [name, value] of Object.entries(env)) {
+        if (!value.startsWith(ENV_REFERENCE_PREFIX))
+            continue;
+        const label = `environment '${envPath}' env '${name}'`;
+        env[name] =
+            ENV_REFERENCE_PREFIX +
+                (await resolveCredentialReference(value.slice(ENV_REFERENCE_PREFIX.length), label, apis, applied, connections));
+    }
+    const defaults = (body.credentials ?? []);
+    for (const [index, entry] of defaults.entries()) {
+        const label = `environment '${envPath}' credentials[${index}]`;
+        entry.credential = await resolveCredentialReference(String(entry.credential), label, apis, applied, connections);
+    }
     // A declared record's token, or an imported slug, becomes the record's id; `null` stays, naming hosted
     // compute.
     const providerRef = launchSpec.computeProviderId;

package/dist/engine/refusals.d.ts

@@ -144,10 +144,5 @@ export declare function byokUnsetSourceMessage(slug: string, modelProvider: stri
  * apply lane reaches through {@link refusalOf}.
  */
 export declare function gatewayKeyPairRefusal(keySlug: string, secretSlug: string, pair: LiveGatewayKeyPair, team: DesiredTeam | undefined, pairContext: TeamIdentityRefusal["pairContext"] | undefined): RefusalVerdict | null;
-/**
- * Lives here rather than in the gateway-key lane because the classifier's message names it and this module
- * must stay a leaf; the lane re-exports it.
- */
-export declare const PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY = "sfdk.pendingGatewayKeyToken";
 /** The named refusal for a mint that succeeded but whose paired-Secret token write did not. */
 export declare function pendingGatewayKeyTokenRotationMessage(slug: string, secretSlug: string): string;

package/dist/engine/refusals.js

@@ -12,6 +12,7 @@
 // nothing rather than guessing. No verdict can carry a credential: the classifiers read source RECIPES.
 import { connectorImmutableFields } from "../constructs/connector.js";
 import { isGatewayKeyRecipe } from "../core/gateway-key-recipe.js";
+import { PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY } from "../core/labels.js";
 import { ApplyError, classifyTeamIdentity, subsetDeepEqual, teamIdentityConflict, } from "./apply-core.js";
 import { isPartiallySuppliedRecipe, missingRootEnvNames, pendingCredentialWrite, } from "./secrets-apply.js";
 import { managedChatConnectionRefusalMessage } from "./connection-readiness.js";
@@ -266,11 +267,6 @@ function pairedSecretAbsentMessage(slug, secretSlug) {
     return (`gateway key '${slug}': the key already exists but its paired secret '${secretSlug}' does not, so ` +
         `there is no token to write and none can be recovered. ${gatewayKeyRotationRemedy(slug)}`);
 }
-/**
- * Lives here rather than in the gateway-key lane because the classifier's message names it and this module
- * must stay a leaf; the lane re-exports it.
- */
-export const PENDING_GATEWAY_KEY_TOKEN_LABEL_KEY = "sfdk.pendingGatewayKeyToken";
 /** The named refusal for a mint that succeeded but whose paired-Secret token write did not. */
 export function pendingGatewayKeyTokenRotationMessage(slug, secretSlug) {
     return (`gateway key '${slug}': its paired secret '${secretSlug}' still carries the pending marker ` +

package/dist/engine/secrets-apply.d.ts

@@ -129,21 +129,17 @@ export declare function metadataInjectionChange(desired: InjectionRecipe | undef
     injection: InjectionRecipe | null;
 } | undefined;
 /**
- * The hosts delta for the value-less PATCH path, compared EXACTLY rather than as a subset: a live row at `[]`
- * after the platform added the column must take a declared list, and a declared `[]` must clear a live one.
- * `undefined` when the plan states no hosts at all (a plan written before the field) or they already match.
+ * A declared secret's recipe as the plan carries it, its hosts inside it. A plan written while hosts sat beside the
+ * recipe has them moved in, so it applies as it did; with no recipe they were never presentable and are dropped.
  */
-export declare function metadataHostsChange(desired: readonly string[] | undefined, live: readonly string[] | undefined): {
-    hosts: string[];
-} | undefined;
-/** A declared secret's hosts as the plan carries them; `undefined` for a plan written before the field. */
-export declare function declaredSecretHosts(payload: unknown): string[] | undefined;
+export declare function declaredSecretInjection(payload: unknown): InjectionRecipe | undefined;
 /**
  * The write kinds carry value-free identifiers for the confirmation prompt, never the value itself.
  *   - `overwrite`       — values are never readable, so any supplied value overwrites.
  *   - `noop-resolve`    — resolve the id and write nothing, which protects the live credential from an
  *                         empty overwrite.
- *   - `metadata-update` — a recipe or hosts edit changes no secret VALUE, so it must not be dropped as a noop.
+ *   - `metadata-update` — a recipe edit, its hosts included, changes no secret VALUE, so it must not be dropped as
+ *                         a noop.
  *   - `skip-empty`      — the reconcile engine turns this into the named preflight error.
  */
 export type SecretDecision = {
@@ -159,13 +155,13 @@ export type SecretDecision = {
 } | {
     kind: "metadata-update";
     injection?: InjectionRecipe | null;
-    hosts?: string[];
+    labels?: Record<string, string | null>;
 } | {
     kind: "skip-empty";
 };
 /**
- * `meta.injectionChange` and `meta.hostsChange` steer only the no-value-plus-exists branch, since a fresh
- * value already writes the recipe and the hosts through the create/overwrite body.
+ * `meta.injectionChange` and `meta.labelsChange` steer only the no-value-plus-exists branch, since a fresh value
+ * already writes the recipe and the label move through the create/overwrite body.
  *
  * `meta.commandLinePending` is the value-free branch, and it is load-bearing: a `cli:`-backed recipe has no
  * bytes yet when this runs, because the collection pass deliberately happens AFTER the confirmation this
@@ -179,8 +175,8 @@ export declare function decideSecretWrite(resolvedValue: string | undefined, exi
     injectionChange?: {
         injection: InjectionRecipe | null;
     };
-    hostsChange?: {
-        hosts: string[];
+    labelsChange?: {
+        labels: Record<string, string | null>;
     };
     commandLinePending?: boolean;
 }): SecretDecision;

package/dist/engine/secrets-apply.js

@@ -306,25 +306,20 @@ export function metadataInjectionChange(desired, live) {
     return live !== undefined ? { injection: null } : undefined;
 }
 /**
- * The hosts delta for the value-less PATCH path, compared EXACTLY rather than as a subset: a live row at `[]`
- * after the platform added the column must take a declared list, and a declared `[]` must clear a live one.
- * `undefined` when the plan states no hosts at all (a plan written before the field) or they already match.
+ * A declared secret's recipe as the plan carries it, its hosts inside it. A plan written while hosts sat beside the
+ * recipe has them moved in, so it applies as it did; with no recipe they were never presentable and are dropped.
  */
-export function metadataHostsChange(desired, live) {
-    if (desired === undefined)
+export function declaredSecretInjection(payload) {
+    const { injection, hosts } = payload;
+    if (injection === undefined)
         return undefined;
-    const current = live ?? [];
-    const same = desired.length === current.length && desired.every((host, index) => host === current[index]);
-    return same ? undefined : { hosts: [...desired] };
-}
-/** A declared secret's hosts as the plan carries them; `undefined` for a plan written before the field. */
-export function declaredSecretHosts(payload) {
-    const hosts = payload.hosts;
-    return Array.isArray(hosts) ? hosts : undefined;
+    if (injection.hosts !== undefined || !Array.isArray(hosts))
+        return injection;
+    return { ...injection, hosts: [...hosts] };
 }
 /**
- * `meta.injectionChange` and `meta.hostsChange` steer only the no-value-plus-exists branch, since a fresh
- * value already writes the recipe and the hosts through the create/overwrite body.
+ * `meta.injectionChange` and `meta.labelsChange` steer only the no-value-plus-exists branch, since a fresh value
+ * already writes the recipe and the label move through the create/overwrite body.
  *
  * `meta.commandLinePending` is the value-free branch, and it is load-bearing: a `cli:`-backed recipe has no
  * bytes yet when this runs, because the collection pass deliberately happens AFTER the confirmation this
@@ -346,8 +341,8 @@ export function decideSecretWrite(resolvedValue, exists, meta) {
     if (!exists) {
         return { kind: "skip-empty" };
     }
-    if (meta.injectionChange !== undefined || meta.hostsChange !== undefined) {
-        return { kind: "metadata-update", ...meta.injectionChange, ...meta.hostsChange };
+    if (meta.injectionChange !== undefined || meta.labelsChange !== undefined) {
+        return { kind: "metadata-update", ...meta.injectionChange, ...meta.labelsChange };
     }
     return { kind: "noop-resolve" };
 }

package/dist/engine/workflow-reconcile.d.ts

@@ -77,7 +77,7 @@ export declare function resolveWorkflow(payload: WorkflowPayload, resolvers: Wor
 export declare function workflowChanges(desired: ResolvedWorkflow, live: LiveWorkflow): WorkflowFieldChange[];
 export interface ReconcileWorkflowsOptions {
     resolvers: WorkflowResolvers;
-    /** The factory whose `sfdk.managedBy` stamp marks the entries apply pins. */
+    /** The factory whose managed-by stamp marks the entries apply pins. */
     factory: string;
     /** Preview only: every write is fenced. */
     dryRun?: boolean;