Skip to content

describeResources() contract doesn't pass entity props — limits live-diff name mapping #39

@lex00

Description

@lex00

The describeResources() plugin contract at packages/core/src/lexicon.ts:199-203 receives:

describeResources?(options: {
  environment: string;
  buildOutput: string;
  entityNames: string[];
}): Promise<Record<string, ResourceMetadata>>

It gets entity names but not entity props. AWS uses CloudFormation logical IDs which happen to match chant entity names, so state diff --live can map declared ↔ observed. Temporal can't: the user declares new TemporalNamespace({ name: "prod" }) (entity export name ns, server-side name prod) and the plugin needs the props to know which server resource maps to which entity.

Because of this gap, the Temporal describeResources() (#27) emits server-side identifiers as keys (namespace/prod, searchAttribute/prod/Project, schedule/prod/daily-report). state diff --live then reports those as orphan (vs. the chant declared set) instead of mapping them back. Honest output but not the full round-trip.

This is the limit on every future lexicon's describeResources() implementation that doesn't have a CloudFormation-style logical ID embedded in the deployed resource.

Tasks

  • Extend the describeResources() options to include entities: Map<string, { entityType: string; props: Record<string, unknown> }> (or similar — could be the actual BuildResult.entities slice for this lexicon)
  • Update packages/core/src/state/snapshot.ts:118 (takeSnapshot()) to pass entity props through
  • Migrate lexicons/aws/src/plugin.ts:474+ to use the new option (no behavior change since AWS already maps via CFN logical IDs, but consume the new arg for forward-compat)
  • Migrate lexicons/temporal/src/describe-resources.ts to use entity props for name mapping: e.g. for each chant TemporalNamespace entity, look up its declared name prop and map the discovered server-side namespace back to the chant entity name as the result key
  • Add a unit test that confirms the entity-name round-trip for Temporal (declared ns with name: "prod" → result key ns, not namespace/prod)
  • Document the new contract in the lexicon-authoring guide

Done when

  • state diff --live against a Temporal-backed env with declared ns reports the entity by chant name, not by namespace/prod server-side prefix
  • AWS lexicon continues to work unchanged
  • All existing snapshot/diff tests still pass

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions