@homeflare/alchemy 0.42.0 → 0.44.0

package/src/litellm/toolset.test.ts

@@ -0,0 +1,198 @@
+/**
+ * `LiteLLM.Toolset` through Alchemy's real Plan and Apply over the fake proxy
+ * (`fake-toolset-litellm.ts`): create, no-op, adopt by name, update, rename and delete.
+ *
+ * ★ EVERY VALUE IS `FAKE-*`.
+ * ⚠️ WHAT THE FAKE MODELS IS READ FROM THE 1.103.0 SOURCE, NOT MEASURED ON A LIVE PROXY (its header).
+ */
+import { expect, test } from 'bun:test';
+import { credentials } from '@distilled.cloud/litellm/Credentials';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { FAKE_BASE } from './fake-litellm.ts';
+import { FAKE_KEY } from './fake-registry-base.ts';
+import {
+  type FakeToolsetLitellm,
+  startFakeToolsetLitellm,
+  toolsetRow,
+} from './fake-toolset-litellm.ts';
+import { fakeStack, writesOf } from './fake-stack.ts';
+import { LiteLLMToolset } from './toolset.ts';
+import { deleteToolset } from './toolset-operations.ts';
+import type { ToolsetProps } from './toolset-types.ts';
+
+const stack = (fake: FakeToolsetLitellm) =>
+  fakeStack({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE }, fake.fetch);
+const declare = (props: ToolsetProps, name = 'Web') =>
+  Effect.gen(function* () {
+    yield* LiteLLMToolset(name, props);
+  });
+
+const web: ToolsetProps = {
+  description: 'FAKE web tools',
+  tools: [
+    { serverId: 'FAKE-server-a', toolName: 'search' },
+    { serverId: 'FAKE-server-b', toolName: 'fetch' },
+  ],
+  toolsetName: 'FAKE-web',
+};
+
+test('creates a toolset with the pairs, remembers the id the proxy issued, then writes nothing', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  expect(await same.deploy(declare(web))).toEqual({ Web: 'create' });
+  expect(fake.toolsets()[0]).toMatchObject({
+    description: 'FAKE web tools',
+    tools: web.tools.map((tool) => ({ server_id: tool.serverId, tool_name: tool.toolName })),
+    toolset_name: 'FAKE-web',
+  });
+  const before = fake.requests().length;
+  expect(await same.deploy(declare(web))).toEqual({ Web: 'noop' });
+  expect(writesOf(fake.requests().slice(before))).toEqual([]);
+});
+
+test('the list is used ONLY to adopt: with state, every read is by id and the list is never asked', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(web));
+  const before = fake.requests().length;
+  await same.deploy(declare({ ...web, description: 'FAKE changed' }));
+  const paths = fake
+    .requests()
+    .slice(before)
+    .map((each) => `${each.method} ${each.path}`);
+  expect(paths).not.toContain('GET /v1/mcp/toolset');
+  expect(paths.some((path) => path.startsWith('GET /v1/mcp/toolset/FAKE-toolset-'))).toBe(true);
+});
+
+test('a changed selection is an update that sends the id and ONLY the changed field', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(web));
+  const planned = await same.deploy(
+    declare({ ...web, tools: [{ serverId: 'FAKE-server-a', toolName: 'search' }] }),
+  );
+  expect(planned).toEqual({ Web: 'update' });
+  expect(fake.bodies().at(-1)).toEqual({
+    tools: [{ server_id: 'FAKE-server-a', tool_name: 'search' }],
+    toolset_id: 'FAKE-toolset-0001',
+  });
+});
+
+test('an empty selection is sent as an explicit empty list, because a null would be a no-op', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(web));
+  await same.deploy(declare({ ...web, tools: [] }));
+  expect(fake.bodies().at(-1)).toMatchObject({ tools: [] });
+  expect(fake.toolsets()[0]?.['tools']).toEqual([]);
+});
+
+test('a rename is an update of the SAME row', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(web));
+  expect(await same.deploy(declare({ ...web, toolsetName: 'FAKE-renamed' }))).toEqual({
+    Web: 'update',
+  });
+  expect(fake.toolsets()).toHaveLength(1);
+  expect(fake.toolsets()[0]).toMatchObject({
+    toolset_id: 'FAKE-toolset-0001',
+    toolset_name: 'FAKE-renamed',
+  });
+});
+
+test('a live row is Unowned: refused without --adopt, adopted by name with it, and a matching row writes nothing', async () => {
+  const live = toolsetRow({
+    description: 'FAKE web tools',
+    tools: [
+      { server_id: 'FAKE-server-b', tool_name: 'fetch' },
+      { server_id: 'FAKE-server-a', tool_name: 'search' },
+    ],
+    toolset_id: 'FAKE-live-1',
+    toolset_name: 'FAKE-web',
+  });
+  const fake = startFakeToolsetLitellm({ seed: [live] });
+  const engine = stack(fake);
+  await expect(engine.deploy(declare(web))).rejects.toThrow();
+  expect(writesOf(fake.requests())).toEqual([]);
+  expect(Object.values(await engine.deploy(declare(web), { adopt: true }))).toEqual(['adopted']);
+  expect(writesOf(fake.requests())).toEqual([]);
+});
+
+test('adopting a toolset with MORE tools than declared corrects it, and keeps undeclared text', async () => {
+  const wide = toolsetRow({
+    description: 'written by a person',
+    tools: [
+      { server_id: 'FAKE-server-a', tool_name: 'search' },
+      { server_id: 'FAKE-server-b', tool_name: 'fetch' },
+      { server_id: 'FAKE-server-b', tool_name: 'FAKE-extra' },
+    ],
+    toolset_id: 'FAKE-live-2',
+    toolset_name: 'FAKE-web',
+  });
+  const fake = startFakeToolsetLitellm({ seed: [wide] });
+  const { description: _kept, ...withoutDescription } = web;
+  await stack(fake).deploy(declare(withoutDescription), { adopt: true });
+  expect(fake.toolsets()[0]?.['tools']).toHaveLength(2);
+  expect(fake.toolsets()[0]?.['description']).toBe('written by a person');
+  expect(fake.bodies()[0]).not.toHaveProperty('description');
+});
+
+test('a list that swallowed a database error cannot hide an existing name: the create fails on the 409', async () => {
+  // ⛔ measured in the source: list_mcp_toolsets answers [] on any exception
+  const live = toolsetRow({ toolset_id: 'FAKE-live-3', toolset_name: 'FAKE-web' });
+  const fake = startFakeToolsetLitellm({ listSwallowsErrors: true, seed: [live] });
+  await expect(stack(fake).deploy(declare(web))).rejects.toThrow();
+  expect(fake.toolsets()).toHaveLength(1);
+});
+
+test('a refused declaration fails the plan before a single request', async () => {
+  for (const props of [
+    { ...web, toolsetName: ' ' },
+    { ...web, toolsetName: 'a/b' },
+    { ...web, description: ' ' },
+    { ...web, tools: [{ serverId: '', toolName: 'search' }] },
+    { ...web, tools: [web.tools[0], web.tools[0]] as never },
+  ]) {
+    const fake = startFakeToolsetLitellm();
+    await expect(stack(fake).deploy(declare(props))).rejects.toThrow();
+    expect(fake.requests()).toEqual([]);
+  }
+});
+
+test('removing the declaration RETAINS the toolset', async () => {
+  const fake = startFakeToolsetLitellm();
+  const same = stack(fake);
+  await same.deploy(declare(web));
+  await same.deploy(Effect.void);
+  expect(fake.toolsets()).toHaveLength(1);
+});
+
+const run = <A, E>(fetchFn: typeof globalThis.fetch, effect: Effect.Effect<A, E, unknown>) =>
+  Effect.runPromise(
+    effect.pipe(
+      Effect.provide(FetchHttpClient.layer),
+      Effect.provide(Layer.succeed(FetchHttpClient.Fetch, fetchFn)),
+      Effect.provide(credentials({ apiKey: FAKE_KEY, baseUrl: FAKE_BASE })),
+    ) as Effect.Effect<A, E, never>,
+  );
+
+test('delete answers 202 with no body, and a missing id is swallowed only because a by-id read says so', async () => {
+  const fake = startFakeToolsetLitellm({
+    seed: [toolsetRow({ toolset_id: 'FAKE-live-4', toolset_name: 'FAKE-web' })],
+  });
+  await run(fake.fetch, deleteToolset('FAKE-live-4'));
+  expect(fake.toolsets()).toEqual([]);
+  await run(fake.fetch, deleteToolset('FAKE-live-4'));
+});
+
+test('a delete refused for lack of rights re-raises the ORIGINAL error and the row stays', async () => {
+  const fake = startFakeToolsetLitellm({
+    forbidWrites: true,
+    seed: [toolsetRow({ toolset_id: 'FAKE-live-5', toolset_name: 'FAKE-web' })],
+  });
+  await expect(run(fake.fetch, deleteToolset('FAKE-live-5'))).rejects.toThrow();
+  expect(fake.toolsets()).toHaveLength(1);
+});

package/src/litellm/toolset.ts

@@ -0,0 +1,151 @@
+/**
+ * `LiteLLM.Toolset` — one row of LiteLLM's MCP toolset table (`/v1/mcp/toolset`): a named selection of
+ * `{ server_id, tool_name }` pairs a key or team can be granted instead of whole servers. Props and
+ * what is left out: toolset-types.ts.
+ *
+ * ★ ADOPT BY NAME. `toolset_name` is unique, so `toolsetName` finds the one live row (from the LIST,
+ *   which is the only by-name lookup the API has, and which cannot prove absence: toolset-operations.ts).
+ *   A live row with no state is `Unowned`, so it needs `--adopt`.
+ * ★ THE ID IS THE PROXY'S and is what state remembers; every later read is BY ID, from the table.
+ * ★ `defaultRemovalPolicy: 'retain'` — deleting a toolset does not detach it: teams and keys that hold
+ *   its id keep a dangling grant, and every caller reaching MCP through it loses the tools.
+ * ⚠️ NO LICENCE GATE ON THESE ROUTES: `mcp_management_endpoints.py`'s toolset block has no
+ *   `premium_user` check (1.103.0), and docs.litellm.ai/docs/mcp_toolsets makes no Enterprise statement.
+ *   Writes need PROXY_ADMIN (403 otherwise).
+ * ⛔ NO LITELLM CREDENTIAL IS A PROP; `litellmProviders`' layer supplies `Credentials`.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import * as Provider from 'alchemy/Provider';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import {
+  LitellmRegistryAbsentAfterWriteError,
+  LitellmRegistryAmbiguousError,
+  LitellmRegistryNotConvergedError,
+  LitellmRegistryUnreadableError,
+} from './registry-errors.ts';
+import { dieIfInvalid, failIfInvalid } from './registry-support.ts';
+import { createBody, differing, firstProblem, updateBody } from './toolset-form.ts';
+import {
+  createToolset,
+  deleteToolset,
+  listToolsets,
+  readToolset,
+  updateToolset,
+} from './toolset-operations.ts';
+import type { ToolsetAttributes, ToolsetProps } from './toolset-types.ts';
+
+export type { ToolsetAttributes, ToolsetProps };
+export type { RegistryError as ToolsetError } from './registry-errors.ts';
+
+const RESOURCE = 'LiteLLM.Toolset';
+
+export interface LiteLLMToolset extends Resource<
+  'LiteLLM.Toolset',
+  ToolsetProps,
+  ToolsetAttributes
+> {}
+
+export const LiteLLMToolset = Resource<LiteLLMToolset>('LiteLLM.Toolset', {
+  defaultRemovalPolicy: 'retain',
+});
+
+export const isLiteLLMToolset = (value: unknown): value is LiteLLMToolset =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.Toolset';
+
+/**
+ * The live row this declaration means: BY ID from the table when state has one (a vanished row is
+ * `undefined`, never taken over by name), else by name from the list. Two rows sharing a name would
+ * mean the unique index is gone; refused, never guessed.
+ */
+const locate = (props: ToolsetProps, output: ToolsetAttributes | undefined) =>
+  Effect.gen(function* () {
+    if (output !== undefined) return yield* readToolset(output.toolsetId);
+    const named = (yield* listToolsets()).filter((row) => row.toolsetName === props.toolsetName);
+    if (named.length > 1) {
+      return yield* Effect.fail(
+        new LitellmRegistryAmbiguousError({
+          ids: named.map((row) => row.toolsetId),
+          name: props.toolsetName,
+          resource: RESOURCE,
+        }),
+      );
+    }
+    return named[0];
+  });
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel. */
+export const toolsetHandlers = {
+  /** ⛔ With no `output` this is the adoption probe, so the refusals run here too (registry-support.ts). */
+  read: ({ olds, output }: { olds: ToolsetProps; output: ToolsetAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (output === undefined) {
+        yield* dieIfInvalid(RESOURCE, String(olds.toolsetName), firstProblem(olds));
+      }
+      const live = yield* locate(olds, output);
+      if (live === undefined) return undefined;
+      return output === undefined ? Unowned(live) : live;
+    }),
+
+  diff: ({ news, output }: { news: Input<ToolsetProps>; output: ToolsetAttributes | undefined }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* failIfInvalid(RESOURCE, String(news.toolsetName), firstProblem(news));
+      if (output === undefined) return undefined;
+      return differing(output, news).length === 0
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({ news, output }: { news: ToolsetProps; output: ToolsetAttributes | undefined }) =>
+    Effect.gen(function* () {
+      yield* failIfInvalid(RESOURCE, String(news.toolsetName), firstProblem(news));
+      const before = yield* locate(news, output);
+      let toolsetId: string;
+      if (before === undefined) {
+        const created = yield* createToolset(createBody(news));
+        if (created === undefined) {
+          return yield* Effect.fail(
+            new LitellmRegistryUnreadableError({
+              reason: 'the create answered something that is not a toolset',
+              resource: RESOURCE,
+            }),
+          );
+        }
+        toolsetId = created.toolsetId;
+      } else {
+        toolsetId = before.toolsetId;
+        if (differing(before, news).length > 0) yield* updateToolset(updateBody(news, before));
+      }
+
+      // ★ BY ID FROM THE TABLE, never the list: the list is the caller-narrowed, error-swallowing view.
+      const after = yield* readToolset(toolsetId);
+      if (after === undefined) {
+        return yield* Effect.fail(
+          new LitellmRegistryAbsentAfterWriteError({ name: news.toolsetName, resource: RESOURCE }),
+        );
+      }
+      const left = differing(after, news);
+      if (left.length > 0) {
+        return yield* Effect.fail(
+          new LitellmRegistryNotConvergedError({
+            fields: left,
+            name: news.toolsetName,
+            resource: RESOURCE,
+          }),
+        );
+      }
+      return after;
+    }),
+
+  delete: ({ output }: { output: ToolsetAttributes }) => deleteToolset(output.toolsetId),
+
+  /** ⛔ EMPTY: adoption is an explicit act (`--adopt`), and no ownership mark exists to filter by. */
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMToolsetProvider = () =>
+  Provider.effect(LiteLLMToolset, Effect.succeed(LiteLLMToolset.Provider.of(toolsetHandlers)));

package/src/openbao/auth-role-form.test.ts

@@ -43,3 +43,40 @@ describe('auth role secret_id TTL', () => {
     expect(matches(attributesOf(PROPS, { ...live, secret_id_ttl: 0 }), PROPS)).toBe(false);
   });
 });
+
+describe('auth role token_period', () => {
+  const LIVE = {
+    bind_secret_id: true,
+    secret_id_num_uses: 0,
+    secret_id_ttl: 7776000,
+    token_max_ttl: 3600,
+    token_period: 0,
+    token_policies: ['default', 'host-cert'],
+    token_ttl: 900,
+  };
+
+  it('omits token_period from the SDK write when the prop is unset', async () => {
+    expect((await Effect.runPromise(authRoleRequest(PROPS))).token_period).toBeUndefined();
+  });
+
+  it('writes 24h as the equivalent SDK seconds, never legacy period', async () => {
+    const props = { ...PROPS, tokenPeriod: '24h' };
+    const request = await Effect.runPromise(authRoleRequest(props));
+    expect(request.token_period).toBe(86400);
+    expect(request).not.toHaveProperty('period');
+  });
+
+  it('reads a live token_period back and matches an equivalent declaration', () => {
+    const props = { ...PROPS, tokenPeriod: '24h' };
+    const attributes = attributesOf(props, { ...LIVE, token_period: 86400 });
+    expect(attributes.tokenPeriod).toBe('1d');
+    expect(matches(attributes, props)).toBe(true);
+    expect(matches(attributesOf(props, { ...LIVE, token_period: 3600 }), props)).toBe(false);
+  });
+
+  it('leaves an unmanaged live token_period out of drift when the prop is unset', () => {
+    const attributes = attributesOf(PROPS, { ...LIVE, token_period: 86400 });
+    expect(attributes.tokenPeriod).toBe('1d');
+    expect(matches(attributes, PROPS)).toBe(true);
+  });
+});

package/src/openbao/auth-role-form.ts

@@ -16,6 +16,14 @@ export interface BaoAuthRoleProps {
   bindSecretId?: boolean;
   /** `0` means unlimited uses — the shape reconcile.sh writes for headless roles. */
   secretIdNumUses?: number;
+  /**
+   * Token period, e.g. `24h` — set only for a periodic (forever-renewable) role, where
+   * `tokenTtl`/`tokenMaxTtl` are conventionally `'0'`. Omitted means this declaration does not
+   * manage the field: a live role's `token_period` (however it got set) is left untouched, the
+   * same way an omitted `bindSecretId` is. See house `openbao/approles.ts` for the role this
+   * unblocks — a periodic agent token that was inexpressible with these props.
+   */
+  tokenPeriod?: string;
 }
 
 export interface BaoAuthRoleAttributes {
@@ -26,6 +34,7 @@ export interface BaoAuthRoleAttributes {
   secretIdTtl: string;
   bindSecretId: boolean;
   secretIdNumUses: number;
+  tokenPeriod: string;
   /** SHA-256 of the managed fields — safe to persist; see policy.ts. */
   digest: string;
 }
@@ -64,6 +73,7 @@ export const attributesOf = (
     secretIdTtl: ttlText(ttlSeconds(live['secret_id_ttl']), '0'),
     bindSecretId: bool(live['bind_secret_id'], true),
     secretIdNumUses: int(live['secret_id_num_uses'], 0),
+    tokenPeriod: ttlText(ttlSeconds(live['token_period']), '0'),
   };
   return { ...attrs, digest: sha256(JSON.stringify(attrs)) };
 };
@@ -88,6 +98,7 @@ export const matches = (attributes: BaoAuthRoleAttributes, props: BaoAuthRolePro
     sameTtl(props.tokenMaxTtl, attributes.tokenMaxTtl) &&
     sameTtl(props.secretIdTtl, attributes.secretIdTtl) &&
     (props.bindSecretId === undefined || attributes.bindSecretId === props.bindSecretId) &&
-    (props.secretIdNumUses === undefined || attributes.secretIdNumUses === props.secretIdNumUses)
+    (props.secretIdNumUses === undefined || attributes.secretIdNumUses === props.secretIdNumUses) &&
+    (props.tokenPeriod === undefined || sameTtl(props.tokenPeriod, attributes.tokenPeriod))
   );
 };

package/src/openbao/auth-role-wire.test.ts

@@ -16,6 +16,7 @@ const DATA = {
   secret_id_num_uses: 0,
   secret_id_ttl: 7776000,
   token_max_ttl: 3600,
+  token_period: 0,
   token_policies: ['host-cert'],
   token_ttl: 900,
 };

package/src/openbao/auth-role-wire.ts

@@ -35,6 +35,7 @@ const completeRole = (live: AppRoleReadRoleResponse): boolean =>
   seconds(live.secret_id_ttl) &&
   seconds(live.token_ttl) &&
   seconds(live.token_max_ttl) &&
+  seconds(live.token_period) &&
   Array.isArray(live.token_policies) &&
   live.token_policies.every((policy) => typeof policy === 'string');
 
@@ -56,7 +57,14 @@ export const authRoleRequest = (props: BaoAuthRoleProps) =>
     const tokenTtl = parseDuration(props.tokenTtl);
     const tokenMaxTtl = parseDuration(props.tokenMaxTtl);
     const secretIdTtl = parseDuration(props.secretIdTtl);
-    if (!seconds(tokenTtl) || !seconds(tokenMaxTtl) || !seconds(secretIdTtl)) {
+    const tokenPeriod =
+      props.tokenPeriod === undefined ? undefined : parseDuration(props.tokenPeriod);
+    if (
+      !seconds(tokenTtl) ||
+      !seconds(tokenMaxTtl) ||
+      !seconds(secretIdTtl) ||
+      (props.tokenPeriod !== undefined && !seconds(tokenPeriod))
+    ) {
       return yield* Effect.fail(
         new BaoError(0, 'POST', readPath(props.name), ['invalid role TTL duration']),
       );
@@ -64,6 +72,9 @@ export const authRoleRequest = (props: BaoAuthRoleProps) =>
     // ★ The former CLI-style body used strings for every k=v. The SDK schema uses seconds,
     // booleans and arrays; omitted knobs stay omitted on update.
     // pathRoleCreateUpdate preserves absent bind_secret_id/secret_id_num_uses on existing roles.
+    // ⛔ token_period, not period — the vendor doc on both fields says period is legacy and loses
+    // to token_period when both are set (approle.ts AppRoleWriteRoleRequest); this Resource only
+    // ever emits the modern field.
     const request: AppRoleWriteRoleRequest = {
       ...identity(props.name),
       token_policies: [...props.tokenPolicies],
@@ -72,6 +83,7 @@ export const authRoleRequest = (props: BaoAuthRoleProps) =>
       secret_id_ttl: secretIdTtl,
       ...(props.bindSecretId === undefined ? {} : { bind_secret_id: props.bindSecretId }),
       ...(props.secretIdNumUses === undefined ? {} : { secret_id_num_uses: props.secretIdNumUses }),
+      ...(tokenPeriod === undefined ? {} : { token_period: tokenPeriod }),
     };
     return request;
   });

package/src/openbao/distilled-retry.test.ts

@@ -25,6 +25,7 @@ const ROLE = {
   secret_id_num_uses: 0,
   secret_id_ttl: 0,
   token_max_ttl: 3600,
+  token_period: 0,
   token_policies: ['default'],
   token_ttl: 900,
 };

package/src/openbao/fake-engines-roles.ts

@@ -57,7 +57,13 @@ export const wireRoles = (): Store =>
   store<Stored>(
     (path, body, before) =>
       path.startsWith('auth/approle/role/')
-        ? { bind_secret_id: true, secret_id_num_uses: 0, ...before, ...typed(body) }
+        ? {
+            bind_secret_id: true,
+            secret_id_num_uses: 0,
+            token_period: 0,
+            ...before,
+            ...typed(body),
+          }
         : typed(body),
     (path) => keyOf(path),
   );

package/src/ownership/ownership.test.ts

@@ -12,7 +12,7 @@ import * as Effect from 'effect/Effect';
 import { refuseTakeover } from './adopt.ts';
 import { ownedRead } from './probe.ts';
 import { noteResume, noteUnfinished, resumes } from './resume.ts';
-import { forgetRefusedCreate, isCreate, recordedInstance } from './rows.ts';
+import { forgetRefusedCreate, isCreate, olderGenerationIds, recordedInstance } from './rows.ts';
 import { row, withStore } from './store-fixture.ts';
 
 describe('recordedInstance', () => {
@@ -50,6 +50,38 @@ describe('isCreate', () => {
   });
 });
 
+describe('olderGenerationIds', () => {
+  test('collects attr.id from every generation older than the instance, through the old chain', async () => {
+    const rows = {
+      A: {
+        ...row('A', 'new', { ...row('A', 'older'), attr: { id: 'older-id' } }),
+        attr: { id: 'new-id' },
+      },
+    };
+    expect(await withStore(rows, olderGenerationIds('A', 'new'))).toEqual(['older-id']);
+  });
+
+  test('walks a former FQN the instance moved away from (renamedFrom)', async () => {
+    // Z is declared renamedFrom('X'). beta.79 moves the row (preserving instanceId) and deletes
+    // the former FQN; while a pre-move row still sits at X, the FormerFqns walk finds it and
+    // collects the older generation it holds.
+    const rows = {
+      Z: row('Z', 'new'),
+      X: {
+        ...row('X', 'new', { ...row('X', 'older'), attr: { id: 'older-id' } }),
+        attr: { id: 'new-id' },
+      },
+    };
+    expect(await withStore(rows, olderGenerationIds('Z', 'new'))).toEqual(['older-id']);
+  });
+
+  test('the current generation itself is skipped, and an empty store answers nothing', async () => {
+    const rows = { A: { ...row('A', 'new'), attr: { id: 'new-id' } } };
+    expect(await withStore(rows, olderGenerationIds('A', 'new'))).toEqual([]);
+    expect(await Effect.runPromise(olderGenerationIds('A', 'new'))).toEqual([]);
+  });
+});
+
 describe('forgetRefusedCreate', () => {
   test('drops only the creating row of this instance, with no attributes', async () => {
     const rows: Record<string, ResourceState> = {

package/src/ownership/rows.ts

@@ -99,6 +99,59 @@ export const isCreate = (fqn: string, instanceId: string): Effect.Effect<boolean
     (generation) => generation?.status === 'creating',
   );
 
+const idOf = (attr: unknown): string | undefined => {
+  if (typeof attr !== 'object' || attr === null) return undefined;
+  const id = (attr as { readonly id?: unknown }).id;
+  return typeof id === 'string' && id !== '' ? id : undefined;
+};
+
+/**
+ * `attr.id` on every generation OLDER than `instanceId` in this FQN's state chain (and a former
+ * FQN `renamedFrom` names). Walks `old` the way {@link generationOf} does, and skips the current
+ * generation itself.
+ * ⛔ THOSE IDS ARE NOT THIS GENERATION'S. A `replacing` row's reconcile runs with no attributes, so
+ *   a live row found by name can be the previous generation's own deployment. Recording that id on
+ *   the new generation makes both the same id, and `destroy()` then deletes the old generation by
+ *   it (Apply.ts, the retain check near 2168 and the provider delete that follows when the policy
+ *   is not `retain`). A same-instance `old` snapshot (an `updating` row) is not one of these.
+ */
+export const olderGenerationIds = (
+  fqn: string,
+  instanceId: string,
+): Effect.Effect<readonly string[]> =>
+  Effect.gen(function* () {
+    const found = yield* storeOf;
+    if (found === undefined) return [];
+    const ids: string[] = [];
+    for (const at of [fqn, ...(found.resources[fqn]?.FormerFqns ?? [])]) {
+      collectOlder(yield* rowAt(found.store, found.where, at), instanceId, ids);
+    }
+    return ids;
+  });
+
+/**
+ * Once `instanceId` has been seen, collect `attr.id` from generations with a DIFFERENT instance
+ * id. An `updating` row's `old` is the same instance's pre-update snapshot (Apply.ts), not a
+ * replacement generation — that snapshot's id is the row this apply is already writing.
+ */
+const collectOlder = (row: unknown, instanceId: string, ids: string[]): void => {
+  let at = row;
+  let seen = false;
+  while (typeof at === 'object' && at !== null && !isActionState(at as never)) {
+    const generation = at as Generation;
+    if (!seen) {
+      seen = generation.instanceId === instanceId;
+      at = generation.old;
+      continue;
+    }
+    if (generation.instanceId !== instanceId) {
+      const id = idOf(generation.attr);
+      if (id !== undefined) ids.push(id);
+    }
+    at = generation.old;
+  }
+};
+
 /**
  * ⛔ A REFUSED CREATE MUST NOT LEAVE A ROW THAT CLAIMS THE OBJECT IT REFUSED. Apply commits a
  *   `creating` row for this instance before it calls reconcile, and a failed reconcile leaves it