@intentius/chant-lexicon-aws 0.44.10 → 0.44.13

package/src/agentcore/trace-render.ts

@@ -0,0 +1,589 @@
+/**
+ * Render an AgentCore session history as dogwood replay-trace text (#1685).
+ *
+ * This module is pure: normalized events in, text out, no transport and no
+ * filesystem. It exists separately from `./trace-fetch.ts` for two reasons.
+ * The Bedrock AgentCore observability surface is in preview and moving, so the
+ * thing most likely to be rewritten is the fetch, and the grammar it renders
+ * into is the thing least likely to move. And the line grammar has two traps in
+ * it that are worth testing byte-for-byte without a mock HTTP stack in the way.
+ *
+ * ## The grammar
+ *
+ * From the #1657 verification (§6, read from
+ * `dogwood-language/src/interpreter/log_parse.rs` at the pinned SHA
+ * `5063bcc2d6d6cf5024d1b0498e6cc8ef52cbcf0c`), one event per line:
+ *
+ * ```
+ * @<timestamp> [scope(principal: <uid>, resource: <uid>)]
+ *              [entities(<uid>: { <attrs> } [in [<uid>, …]], …)]
+ *              [request_context(<group>: { … }, …)]
+ *              <Ns>::Action::"<Name>"::<kind>(<field>: <value>, …)
+ * ```
+ *
+ * The three envelopes are optional and must appear in that order; the trailing
+ * group is the logged record. Blank lines are skipped and there is no comment
+ * syntax, so a `//` inside a value survives.
+ *
+ * ## The two traps
+ *
+ * 1. **`request_context(…)` and the logged record are different bags.** The
+ *    Cedar request is built from the first, temporal predicates match against
+ *    the second, and a field supplied to only one weakens either the Cedar
+ *    check or the temporal check while the replay still exits 0 with a verdict
+ *    that looks authoritative. So every payload group an event carries is
+ *    written to *both*, always — there is no per-event opt-out here, because an
+ *    AgentCore history has no way to express "this field is deliberately
+ *    Cedar-invisible". A decision-kind event with no payload at all is a
+ *    refusal, not a shrug: see {@link renderAgentCoreTrace}.
+ * 2. **Actions must be fully qualified.** `AgentCore::Action::"Transfer"`,
+ *    never `Transfer` — a short name leaves the temporal predicate unmatched
+ *    while Cedar still authorizes. A bare tool name from the history is
+ *    qualified here; an already-qualified one is validated and passed through.
+ *
+ * ## Decoupling
+ *
+ * Nothing here imports the cedar lexicon, and the cedar lexicon imports nothing
+ * from here. The contract between them is the text. The value and event types
+ * below are deliberately shaped so an object built here is *structurally*
+ * assignable to the cedar side's `TraceValue`/`TraceEvent` for anyone who wants
+ * that, but neither package depends on the other to get it, and the rendering
+ * is implemented twice on purpose. Where a choice was free — the space inside
+ * `{ … }`, the `, ` between fields, the order of the record's own injections —
+ * it matches `lexicons/cedar/src/dogwood/trace.ts` byte for byte, so a trace
+ * fetched from AWS and a trace built by hand look the same to a reader and to
+ * the parser.
+ */
+
+/* ── Values ───────────────────────────────────────────────────────────────── */
+
+/** `Ns::Type::"id"` in value position. */
+export interface AgentCoreEntityRef {
+  readonly traceValue: "entity";
+  readonly uid: string;
+}
+
+/** `1.50` — Cedar's decimal surface form, which a JS number cannot carry. */
+export interface AgentCoreDecimal {
+  readonly traceValue: "decimal";
+  readonly text: string;
+}
+
+/** Surface text passed through untouched — the escape hatch, used sparingly. */
+export interface AgentCoreRaw {
+  readonly traceValue: "raw";
+  readonly text: string;
+}
+
+/** A tagged value: one rendered specially rather than by JS type. */
+export type AgentCoreTagged = AgentCoreEntityRef | AgentCoreDecimal | AgentCoreRaw;
+
+/**
+ * Which objects are *really* tagged values.
+ *
+ * Identity, not shape. A tagged value renders as surface text — an `entity`
+ * becomes a bare uid, a `raw` becomes its `text` verbatim — so if membership
+ * were decided by a `traceValue` key, any agent that wrote
+ * `{"traceValue": "raw", "text": "…"}` into a payload could inject arbitrary
+ * unescaped text into both bags of the trace: a forged `callerPrincipal`, an
+ * unbalanced paren, a whole extra field. The payloads this module reads are
+ * written by the agent under observation, which is the last party that should
+ * get to decide what its own trace says. So only the three constructors below
+ * confer the tag, and {@link renderValue} refuses a record that merely looks
+ * tagged rather than rendering it either way.
+ */
+const TAGGED = new WeakSet<object>();
+
+function tag<T extends AgentCoreTagged>(value: T): T {
+  TAGGED.add(value);
+  return value;
+}
+
+/** Anything that can sit in a trace field, in Cedar surface forms. */
+export type AgentCoreTraceValue =
+  | string
+  | number
+  | boolean
+  | AgentCoreTagged
+  | readonly AgentCoreTraceValue[]
+  | { readonly [key: string]: AgentCoreTraceValue };
+
+/** A named group of fields — what one `request_context` envelope entry holds. */
+export type AgentCoreFields = { readonly [key: string]: AgentCoreTraceValue };
+
+/** `Ns::Type::"id"`, `Ns::Action::"Name"` — a fully qualified uid. */
+const QUALIFIED_UID = /^[A-Za-z_][A-Za-z0-9_]*(::[A-Za-z_][A-Za-z0-9_]*)+::"[^"]*"$/;
+/** A bare field, group, namespace or event-kind name. */
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * A history that cannot become an honest trace.
+ *
+ * Thrown rather than worked around. Every case this covers is one where the
+ * alternative is a trace that replays green and proves less than it looks like
+ * it proves, which is the failure mode the whole module is arranged against.
+ */
+export class AgentCoreTraceError extends Error {
+  constructor(
+    message: string,
+    /** 0-based position in the event list, when one event is to blame. */
+    readonly index?: number,
+  ) {
+    super(message);
+    this.name = "AgentCoreTraceError";
+  }
+}
+
+function assertUid(value: string, what: string, index?: number): string {
+  if (!QUALIFIED_UID.test(value)) {
+    throw new AgentCoreTraceError(
+      `agentcore trace: ${what} must be fully qualified, like Ns::Type::"id" — got "${value}"`,
+      index,
+    );
+  }
+  return value;
+}
+
+function assertIdent(value: string, what: string, index?: number): string {
+  if (!IDENT.test(value)) {
+    throw new AgentCoreTraceError(`agentcore trace: ${what} must be an identifier — got "${value}"`, index);
+  }
+  return value;
+}
+
+/** `Ns::Type::"id"`. Validated at construction, so a short name cannot slip through. */
+export function agentCoreEntityRef(uid: string): AgentCoreEntityRef {
+  return tag({ traceValue: "entity", uid: assertUid(uid, "an entity reference") });
+}
+
+/**
+ * A Cedar decimal, written as it should appear (`"1.50"`).
+ *
+ * `context` names the field it came from when there is one, so a payload that
+ * cannot be represented says *where* rather than only *what*.
+ */
+export function agentCoreDecimal(text: string, context?: string): AgentCoreDecimal {
+  if (!/^-?\d+\.\d+$/.test(text)) {
+    const where = context ? ` at ${context}` : "";
+    throw new AgentCoreTraceError(`agentcore trace: a decimal looks like "1.50" — got "${text}"${where}`);
+  }
+  return tag({ traceValue: "decimal", text });
+}
+
+/** Surface text, rendered verbatim. For values this module has no shape for. */
+export function agentCoreRaw(text: string): AgentCoreRaw {
+  return tag({ traceValue: "raw", text });
+}
+
+function isTagged(value: AgentCoreTraceValue): value is AgentCoreTagged {
+  return typeof value === "object" && value !== null && TAGGED.has(value);
+}
+
+/** The five escapes a Cedar string literal needs. Mirrors the cedar lexicon's. */
+function escapeString(value: string): string {
+  return value
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, "\\n")
+    .replace(/\r/g, "\\r")
+    .replace(/\t/g, "\\t");
+}
+
+/** Render one value in the Cedar surface form the trace parser reads. */
+export function renderValue(value: AgentCoreTraceValue): string {
+  if (typeof value === "string") return `"${escapeString(value)}"`;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isInteger(value)) {
+      throw new AgentCoreTraceError(
+        `agentcore trace: ${String(value)} is not an integer — a decimal must be written with agentCoreDecimal("1.50") so its scale survives`,
+      );
+    }
+    // Beyond 2^53 a JS number has already lost the digits an i64 would keep,
+    // and `String(1e21)` is `"1e+21"`, which is not a Cedar integer literal at
+    // all. Either way the trace would carry a number that is not the number the
+    // agent saw.
+    if (!Number.isSafeInteger(value)) {
+      throw new AgentCoreTraceError(
+        `agentcore trace: ${String(value)} is outside the range a JS number represents exactly, so the trace would carry a different number than the history did — carry it as a string`,
+      );
+    }
+    return String(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(renderValue).join(", ")}]`;
+  if (isTagged(value)) return value.traceValue === "entity" ? value.uid : value.text;
+  if ("traceValue" in value) {
+    // See TAGGED. Rendering it as a record would be a lie about what the agent
+    // wrote; rendering it as a tagged value would let the agent write its own
+    // trace. Neither is on offer.
+    throw new AgentCoreTraceError(
+      `agentcore trace: a payload carries a "traceValue" field, which is the marker this module uses for entity refs, decimals and raw surface text. ` +
+        "Rendering it either way would let the observed agent decide what its own trace says, so it is refused — rename the field at the source, " +
+        "or build the value with agentCoreEntityRef/agentCoreDecimal/agentCoreRaw.",
+    );
+  }
+  return renderFields(value as AgentCoreFields);
+}
+
+/** `{ a: 1, b: "x" }` — a record body, braces included. */
+export function renderFields(fields: AgentCoreFields): string {
+  const parts = Object.entries(fields).map(
+    ([key, value]) => `${assertIdent(key, "a trace field name")}: ${renderValue(value)}`,
+  );
+  return `{ ${parts.join(", ")} }`;
+}
+
+/* ── Normalized events ────────────────────────────────────────────────────── */
+
+/**
+ * One decision-relevant thing that happened in an AgentCore session, in the
+ * shape the fetch normalizes to and the renderer reads.
+ *
+ * This is deliberately *not* the dogwood event shape. It is the semantic shape
+ * of an agent session — who acted, on what, with which payload — so that a
+ * change to the observability surface under preview churn is a change to the
+ * mapping in `./trace-fetch.ts` and not to the grammar below.
+ */
+export interface AgentCoreSessionEvent {
+  /** When it happened, epoch **milliseconds**. Converted to the trace's i64 here. */
+  readonly timeMs: number;
+  /** The session it belongs to. Lands in the logged record as `sessionId`. */
+  readonly sessionId: string;
+  /** Unique within the session. Lands in the logged record as `requestId`. */
+  readonly eventId: string;
+  /**
+   * The dogwood event kind. `request` / `response` / `error` conventionally;
+   * the truth is whichever kinds the project's `.dwschema` marks `decision`,
+   * and that file is not visible from here.
+   */
+  readonly kind: string;
+  /**
+   * The tool or operation. A bare name (`"Transfer"`) is qualified with the
+   * namespace; an already-qualified `Ns::Action::"Name"` is validated and used
+   * as-is. Never rendered short.
+   */
+  readonly action: string;
+  /** Who acted — an actor id, or a fully qualified uid to override the type. */
+  readonly actor: string;
+  /** What was acted on — a runtime/gateway id, or a fully qualified uid. */
+  readonly target: string;
+  /** The call's input payload. Lands in both bags as the `input` group. */
+  readonly input?: AgentCoreFields;
+  /** The call's result. Lands in both bags as the `output` group. */
+  readonly output?: AgentCoreFields;
+  /** A failure's detail. Lands in both bags as the `error` group. */
+  readonly error?: AgentCoreFields;
+  /**
+   * Anything the source carried that has no field of its own. Lands in both
+   * bags as the `attributes` group.
+   */
+  readonly attributes?: AgentCoreFields;
+}
+
+/** How `@<i64>` is derived from `timeMs`. */
+export type AgentCoreTimeOrigin =
+  /** Epoch seconds. Absolute, comparable across sessions, large numbers. */
+  | "epoch-seconds"
+  /** Seconds since the earliest event, so the first line reads `@0`. */
+  | "relative-seconds";
+
+/** What {@link renderAgentCoreTrace} takes. */
+export interface AgentCoreTraceOptions {
+  /** Cedar namespace for actions and entity types. Default `"AgentCore"`. */
+  readonly namespace?: string;
+  /** Entity type for `actor`. Default `"Actor"`. */
+  readonly principalType?: string;
+  /** Entity type for `target`. Default `"Runtime"`. */
+  readonly resourceType?: string;
+  /** Default `"epoch-seconds"`. */
+  readonly origin?: AgentCoreTimeOrigin;
+  /**
+   * Kinds that produce a decision, and so build a Cedar request. Default
+   * `["request"]`, the convention the default event schema follows. A
+   * history-only event never becomes a Cedar request, so an absent payload on
+   * one is not a weakening.
+   */
+  readonly decisionKinds?: readonly string[];
+  /** Weakenings to tolerate. Empty by default — see {@link renderAgentCoreTrace}. */
+  readonly allow?: readonly AgentCoreTraceIssueKind[];
+}
+
+/** What {@link auditAgentCoreEvents} can find. */
+export type AgentCoreTraceIssueKind =
+  /** A decision-kind event with no payload: the Cedar request carries no context. */
+  | "no-request-context"
+  /** Two events in one session sharing an id: `requestId` stops identifying anything. */
+  | "duplicate-event-id";
+
+/** One finding against a normalized history. */
+export interface AgentCoreTraceIssue {
+  readonly kind: AgentCoreTraceIssueKind;
+  /** 0-based position in the *sorted* event list. */
+  readonly index: number;
+  readonly timeMs: number;
+  readonly message: string;
+}
+
+const DEFAULTS = {
+  namespace: "AgentCore",
+  principalType: "Actor",
+  resourceType: "Runtime",
+  origin: "epoch-seconds" as AgentCoreTimeOrigin,
+  decisionKinds: ["request"] as readonly string[],
+};
+
+/** A payload group name → the field on the normalized event. Order is the render order. */
+const GROUPS = ["input", "output", "error", "attributes"] as const;
+
+function payloadGroups(event: AgentCoreSessionEvent): Record<string, AgentCoreFields> {
+  const out: Record<string, AgentCoreFields> = {};
+  for (const group of GROUPS) {
+    const fields = event[group];
+    if (fields && Object.keys(fields).length > 0) out[group] = fields;
+  }
+  return out;
+}
+
+/**
+ * `Ns::Action::"Name"` from a bare tool name, or a qualified action validated.
+ *
+ * The fully-qualified requirement is the second §6 trap: a short name leaves
+ * every temporal predicate unmatched while Cedar still authorizes, so the
+ * replay is green and blind.
+ */
+export function qualifyAction(action: string, namespace: string, index?: number): string {
+  if (action.includes("::")) return assertUid(action, "a trace action", index);
+  if (action.length === 0 || action.includes('"')) {
+    throw new AgentCoreTraceError(
+      `agentcore trace: a bare action name cannot be empty or contain a quote — got "${action}"`,
+      index,
+    );
+  }
+  return `${assertIdent(namespace, "a namespace", index)}::Action::"${action}"`;
+}
+
+/** `Ns::Type::"id"` from a bare id, or a qualified uid validated. */
+export function qualifyUid(id: string, namespace: string, type: string, what: string, index?: number): string {
+  if (id.includes("::")) return assertUid(id, what, index);
+  if (id.length === 0 || id.includes('"')) {
+    throw new AgentCoreTraceError(
+      `agentcore trace: ${what} cannot be empty or contain a quote — got "${id}"`,
+      index,
+    );
+  }
+  return `${assertIdent(namespace, "a namespace", index)}::${assertIdent(type, "an entity type", index)}::"${id}"`;
+}
+
+/**
+ * Order the history the way the interpreter reads it.
+ *
+ * dogwood accumulates history in *file* order, so an out-of-order line changes
+ * what a temporal window sees. A fetch that pages backwards (CloudWatch Logs
+ * hands out the newest first) would otherwise produce a trace whose windows are
+ * quietly wrong, so ordering is settled here rather than being a caller's
+ * problem. Ties keep their original relative order.
+ */
+function sortByTime(events: readonly AgentCoreSessionEvent[]): AgentCoreSessionEvent[] {
+  return events.map((event, index) => ({ event, index }))
+    .sort((a, b) => a.event.timeMs - b.event.timeMs || a.index - b.index)
+    .map(({ event }) => event);
+}
+
+function assertWellFormed(event: AgentCoreSessionEvent, index: number): void {
+  if (typeof event.timeMs !== "number" || !Number.isFinite(event.timeMs)) {
+    throw new AgentCoreTraceError(
+      `agentcore trace: event ${index} has no usable timestamp (${String(event.timeMs)}) — a trace timepoint is an i64 and there is no honest default for a missing one`,
+      index,
+    );
+  }
+  for (const [field, value] of [
+    ["sessionId", event.sessionId],
+    ["eventId", event.eventId],
+    ["actor", event.actor],
+    ["target", event.target],
+    ["action", event.action],
+    ["kind", event.kind],
+  ] as const) {
+    if (typeof value !== "string" || value.length === 0) {
+      throw new AgentCoreTraceError(
+        `agentcore trace: event ${index} has no ${field} — the history is malformed, and a trace with a guessed ${field} replays green while proving nothing`,
+        index,
+      );
+    }
+  }
+}
+
+/**
+ * The weakening checks, applied to a normalized history.
+ *
+ * Everything here is something that makes a replay *weaker* rather than
+ * something that makes it fail, which is exactly the class a green replay run
+ * hides. Structural malformation throws instead: see {@link AgentCoreTraceError}.
+ */
+export function auditAgentCoreEvents(
+  events: readonly AgentCoreSessionEvent[],
+  options: AgentCoreTraceOptions = {},
+): AgentCoreTraceIssue[] {
+  const decisionKinds = new Set(options.decisionKinds ?? DEFAULTS.decisionKinds);
+  const issues: AgentCoreTraceIssue[] = [];
+  const seen = new Set<string>();
+
+  sortByTime(events).forEach((event, index) => {
+    assertWellFormed(event, index);
+    const at = { index, timeMs: event.timeMs };
+
+    if (decisionKinds.has(event.kind) && Object.keys(payloadGroups(event)).length === 0) {
+      issues.push({
+        ...at,
+        kind: "no-request-context",
+        message: `${event.action}::${event.kind} carries no input, output, error or attributes, so its request_context envelope would be empty and every context.* test in a policy silently misses`,
+      });
+    }
+
+    const key = `${event.sessionId}${event.eventId}`;
+    if (seen.has(key)) {
+      issues.push({
+        ...at,
+        kind: "duplicate-event-id",
+        message: `session ${event.sessionId} reports eventId "${event.eventId}" twice, so requestId no longer identifies a decision point and an expectation written against one addresses both`,
+      });
+    }
+    seen.add(key);
+  });
+
+  return issues;
+}
+
+/* ── Rendering ────────────────────────────────────────────────────────────── */
+
+/** One line's worth: the envelopes and the logged record, fully resolved. */
+export interface AgentCoreTraceLine {
+  readonly timestamp: number;
+  readonly action: string;
+  readonly kind: string;
+  readonly scope: { readonly principal: string; readonly resource: string };
+  readonly requestContext: AgentCoreFields;
+  readonly record: AgentCoreFields;
+}
+
+/**
+ * Resolve one normalized event into the envelopes and the logged record.
+ *
+ * Both bags get every payload group; the record additionally gets the event
+ * schema's own injections (`callerPrincipal`, `callerResource`, `sessionId`,
+ * `requestId`), which are never part of the Cedar request. Field order matches
+ * the §6 example line: groups first, then the injections.
+ */
+export function toTraceLine(
+  event: AgentCoreSessionEvent,
+  timestamp: number,
+  options: AgentCoreTraceOptions = {},
+  index?: number,
+): AgentCoreTraceLine {
+  const namespace = options.namespace ?? DEFAULTS.namespace;
+  const principal = qualifyUid(
+    event.actor,
+    namespace,
+    options.principalType ?? DEFAULTS.principalType,
+    "an actor",
+    index,
+  );
+  const resource = qualifyUid(
+    event.target,
+    namespace,
+    options.resourceType ?? DEFAULTS.resourceType,
+    "a target",
+    index,
+  );
+  const groups = payloadGroups(event);
+
+  return {
+    timestamp,
+    action: qualifyAction(event.action, namespace, index),
+    kind: assertIdent(event.kind, "an event kind", index),
+    scope: { principal, resource },
+    requestContext: groups,
+    record: {
+      ...groups,
+      callerPrincipal: agentCoreEntityRef(principal),
+      callerResource: agentCoreEntityRef(resource),
+      sessionId: event.sessionId,
+      requestId: event.eventId,
+    },
+  };
+}
+
+/** One line as the trace parser reads it. Never ends in a newline. */
+export function renderTraceLine(line: AgentCoreTraceLine): string {
+  if (!Number.isSafeInteger(line.timestamp)) {
+    throw new AgentCoreTraceError(`agentcore trace: a timepoint is an i64 — got ${String(line.timestamp)}`);
+  }
+
+  const parts = [`@${line.timestamp}`];
+  parts.push(`scope(principal: ${line.scope.principal}, resource: ${line.scope.resource})`);
+
+  const context = Object.entries(line.requestContext).map(
+    ([group, value]) => `${assertIdent(group, "a request-context group")}: ${renderValue(value)}`,
+  );
+  if (context.length > 0) parts.push(`request_context(${context.join(", ")})`);
+
+  const record = Object.entries(line.record).map(
+    ([key, value]) => `${assertIdent(key, "a trace field name")}: ${renderValue(value)}`,
+  );
+  parts.push(`${line.action}::${line.kind}(${record.join(", ")})`);
+
+  return parts.join(" ");
+}
+
+/** A rendered trace, and what the audit tolerated on the way. */
+export interface AgentCoreTrace {
+  /** The text, one event per line, newline-terminated. */
+  readonly text: string;
+  /** The resolved lines, in render order. */
+  readonly lines: readonly AgentCoreTraceLine[];
+  /** Findings the caller allowed. Empty unless `allow` named something. */
+  readonly issues: readonly AgentCoreTraceIssue[];
+}
+
+/**
+ * Render a normalized AgentCore history as dogwood trace text.
+ *
+ * The inversion of the §6 traps: every payload group lands in both bags, every
+ * action comes out fully qualified, the history is ordered the way the
+ * interpreter reads it, and a history that would produce a weakened trace
+ * throws instead. Naming a kind in `allow` is how a caller says the weakening
+ * is the point — the alternative was a trace that replays green and proves
+ * less than it looks like it proves.
+ */
+export function renderAgentCoreTrace(
+  events: readonly AgentCoreSessionEvent[],
+  options: AgentCoreTraceOptions = {},
+): AgentCoreTrace {
+  const sorted = sortByTime(events);
+  // The audit runs `assertWellFormed` over the same sorted list, so a
+  // structurally broken history throws here before anything is rendered.
+  const issues = auditAgentCoreEvents(sorted, options);
+  const allow = new Set(options.allow ?? []);
+  const blocking = issues.filter((issue) => !allow.has(issue.kind));
+  if (blocking.length > 0) {
+    const detail = blocking.map((i) => `  [${i.kind}] event ${i.index}: ${i.message}`).join("\n");
+    const kinds = [...new Set(blocking.map((i) => `"${i.kind}"`))].join(", ");
+    throw new AgentCoreTraceError(
+      `agentcore trace: this history would weaken its own replay rather than fail it:\n${detail}\n` +
+        `Fix the history, or pass { allow: [${kinds}] } to say the weakening is the point.`,
+    );
+  }
+
+  const origin = options.origin ?? DEFAULTS.origin;
+  const base = origin === "relative-seconds" && sorted.length > 0 ? (sorted[0]?.timeMs ?? 0) : 0;
+  const lines = sorted.map((event, index) =>
+    toTraceLine(event, Math.floor((event.timeMs - base) / 1000), options, index),
+  );
+
+  // An empty history renders as empty text, not as a bare newline: dogwood
+  // skips blank lines, so the two replay identically, and "" is the honest
+  // answer to "what did this session do". Whether an empty trace is worth
+  // replaying is the caller's call — see `trace-fetch.ts`'s `requireEvents`.
+  const text = lines.length > 0 ? lines.map(renderTraceLine).join("\n") + "\n" : "";
+  return { text, lines, issues };
+}

package/src/api/read-client.ts

@@ -135,8 +135,14 @@ function regionScope(
  * string has a slot for one; it borrows the same `us-east-1` default that
  * {@link serviceUrl} already used to build the host, so the signature agrees
  * with the endpoint it is sent to.
+ *
+ * Exported because this decision — sign, or carry the scope and no signature —
+ * belongs to the lexicon's read transport rather than to any one API on it.
+ * `agentcore/trace-fetch.ts` reads `bedrock-agentcore` through the same seam,
+ * and a second copy of this would be a second place for the emulator carve-out
+ * to drift.
  */
-function requestHeaders(
+export function requestHeaders(
   service: string,
   url: string,
   body: string,

package/src/identity-observe.test.ts

@@ -74,9 +74,51 @@ describe("observeByIdentity (#1647)", () => {
     expect(queried.assets).toBeDefined();
   });
 
-  test("an emulator without Cloud Control keeps the absent verdict — never a hole, or pre-first-apply plans stop proposing create", async () => {
+  test("an emulator without Cloud Control at all keeps the absent verdict — never a hole, or pre-first-apply plans stop proposing create", async () => {
     const { resources } = await observeByIdentity(["assets"], bucket, {}, {
-      http: async () => ccError("UnsupportedOperation", "Operation GetResource is not supported."),
+      http: async () => ccError("UnsupportedOperation", "not supported"),
+    });
+    expect(resources.assets).toBeUndefined();
+  });
+
+  // Floci serves ListResources but answers UnsupportedOperation for
+  // GetResource (read-client's own note) — and the emulator is where the carve
+  // walkthrough films the observe beat. Verified against Floci 1.5.34 on the
+  // behold demo: the list leg is what turns the miss into a read.
+  test("GetResource-unsupported falls back to ListResources and matches the identifier (Floci)", async () => {
+    const targets: string[] = [];
+    const { resources } = await observeByIdentity(["assets"], bucket, {}, {
+      http: async (_url, init) => {
+        const target = (init.headers as Record<string, string>)["x-amz-target"] ?? "";
+        targets.push(target);
+        if (target.endsWith("GetResource")) return ccError("UnsupportedOperation", "Operation GetResource is not supported.");
+        return {
+          status: 200,
+          text: JSON.stringify({
+            ResourceDescriptions: [
+              { Identifier: "some-other-bucket", Properties: JSON.stringify({ BucketName: "some-other-bucket" }) },
+              { Identifier: "acme-platform-assets-prod", Properties: JSON.stringify({ BucketName: "acme-platform-assets-prod" }) },
+            ],
+          }),
+        };
+      },
+    });
+    expect(targets.some((t) => t.endsWith("ListResources"))).toBe(true);
+    expect(resources.assets).toMatchObject({
+      type: "AWS::S3::Bucket",
+      physicalId: "acme-platform-assets-prod",
+      status: "EXTERNAL",
+      ownership: "foreign",
+    });
+  });
+
+  test("the list leg missing the identifier keeps the absent verdict", async () => {
+    const { resources } = await observeByIdentity(["assets"], bucket, {}, {
+      http: async (_url, init) => {
+        const target = (init.headers as Record<string, string>)["x-amz-target"] ?? "";
+        if (target.endsWith("GetResource")) return ccError("UnsupportedOperation", "not supported");
+        return { status: 200, text: JSON.stringify({ ResourceDescriptions: [] }) };
+      },
     });
     expect(resources.assets).toBeUndefined();
   });