@salesforce/afv-skills 1.20.0 → 1.22.0

package/skills/agentforce-d360-analyze/references/dc_pipeline_contract.md

@@ -0,0 +1,608 @@
+# DC Pipeline Contract
+
+The DC pipeline for a single Agentforce session runs as three stages in
+sequence:
+
+```
+fetch_dc.py → 24 dc.<name>.json artifacts + dc._session_manifest.json
+assemble_dc.py → dc._session_tree.json (pure in-memory join)
+render_dc.py → dc._session_summary.md (pure tree reader)
+```
+
+Each stage is independently runnable. `fetch_dc.py` chains the two
+downstream stages by default; `--no-assemble` / `--no-render` opt out of
+each. The renderer can also run standalone against a tree produced by a
+prior invocation.
+
+This document owns the shape + invariants of stages 2 and 3. For per-DMO
+field reference of what stage 1 produces, see
+[`dc_dmo_fields.md`](./dc_dmo_fields.md).
+
+---
+
+## 1. Pipeline overview
+
+| Stage | Script | Input | Output | Scope |
+|---|---|---|---|---|
+| Fetch | `scripts/fetch_dc.py` | org + session id | 24 `dc.<name>.json` + `dc._session_manifest.json` | DC Query REST API, 5-wave waterfall |
+| Assemble | `scripts/assemble_dc.py` | fetch outputs | `dc._session_tree.json` | pure in-memory join, no fetches |
+| Render | `scripts/render_dc.py` | tree + manifest | `dc._session_summary.md` | pure tree reader, no DMO loads |
+
+Nothing downstream of fetch issues DC queries. Everything after fetch is
+pure compute over files on disk, which means the renderer can iterate
+on markdown format without re-fetching.
+
+---
+
+## 2. Assembly stage
+
+`scripts/assemble_dc.py` joins the fetched DC rows into a hierarchical
+tree.
+
+### 2.1 Purpose + scope
+
+**Inputs:** 24 `dc.<name>.json` artifacts + `dc._session_manifest.json`
+produced by `scripts/fetch_dc.py`, under `DATA_ROOT/<sid>/`.
+
+**Output:** `dc._session_tree.json` — session-rooted hierarchical view.
+Interaction → Step → Generation → GatewayRequest; audit rows (Tag,
+ObjRecord, Metadata, LLM, Quality, Category, Feedback, FeedbackDetail)
+nested under the right parent.
+
+**Contract:** pure in-memory compute, no new DMO queries, forward-only
+joins on already-fetched rows. Chain-orphan GW calls fall through to a
+timestamp-window rule with an explicit `binding_method` flag.
+
+### 2.2 Inputs
+
+The assembler does **not** hard-code the 24 template names. It reads
+`dc._session_manifest.json` first, then iterates
+`manifest["queries"][*]["name"]` to populate the row map. When
+`fetch_dc.py` adds a 25th template, the row loader picks it up
+automatically — the tree logic only references names it knows how to
+place, so a new DMO is loaded but not rendered until the assembler is
+taught what to do with it.
+
+Per-field schema for every DMO lives in
+[`dc_dmo_fields.md`](./dc_dmo_fields.md).
+
+### 2.3 Declared binding chain
+
+The "normal" path that nests a `GatewayRequest` under its owning
+`LLM_STEP` in the tree. Every edge is a platform-sanctioned forward FK:
+
+```
+Step.ssot__GenerationId__c → Generation.generationId__c
+Generation.generationResponseId__c → GatewayResponse.generationResponseId__c
+GatewayResponse.generationRequestId__c → GatewayRequest.gatewayRequestId__c
+```
+
+**Which Step types populate `ssot__GenerationId__c`?** Only `LLM_STEP`
+(verified live). `ACTION_STEP`, `TOPIC_STEP`, `TRUST_GUARDRAILS_STEP`,
+and `SESSION_END` always have `NOT_SET` here; the chain never resolves
+for them.
+
+**Expected declared-share on typical Agentforce sessions:** minority.
+Most gateway calls on a real session land via the timestamp-window
+fallback, not the declared chain. Sessions that rely on Flow-invoked
+prompt-template actions produce zero declared bindings and many
+timestamp_window bindings — normal, not a defect.
+
+### 2.4 Timestamp-window fallback
+
+Any `GatewayRequest` not reached via the declared chain is placed by
+timestamp containment.
+
+**Window semantics:**
+- **Closed-closed:** `start_ts <= gw_req.timestamp__c <= end_ts`.
+- **Null end_ts** (active session / interaction / step) is treated as
+ `+∞`.
+- **Missing start_ts**: fall through to the next preference tier; never
+ match on start alone.
+- Boundary ties bind to the earlier parent (Step) in preference to the
+ later one (Interaction).
+
+**Tier dominates containment.** Selection order is:
+
+1. Find all Step windows containing the GW timestamp.
+2. Restrict to the highest-preference tier present: `ACTION_STEP` →
+ `TOPIC_STEP` → `TRUST_GUARDRAILS_STEP` → any other (catch-all:
+ LLM_STEP without declared binding, SESSION_END, unknown types —
+ never excluded).
+3. Among those, pick the innermost (shortest-window) Step.
+4. On exact window-size ties, pick the latest `start_ts`.
+
+Example: if both a wide `ACTION_STEP` and a narrower nested `TOPIC_STEP`
+contain the GW timestamp, the `ACTION_STEP` wins because its tier
+dominates — even though TOPIC is innermost.
+
+**Placement fallbacks:**
+- If no Step window matches, attach to the enclosing `Interaction` as a
+ `timestamp_bound_gateway_calls[]` entry (`bound_to_step_id` is null).
+- If no Interaction window matches, land in
+ `session.unbound_gateway_calls[]`.
+
+**Never declared-bound twice.** A Step that already owns a GW via the
+declared chain is excluded from timestamp-window candidates.
+
+### 2.5 `binding_method` enum
+
+Every GatewayRequest in the tree carries exactly one of these:
+
+| Value | When emitted |
+|---|---|
+| `declared` | Placed under a Step via the declared chain in §2.3. |
+| `timestamp_window` | Placed by §2.4 (under a Step or an Interaction). |
+| `unbound` | Neither chain nor window matched; landed in `session.unbound_gateway_calls[]`. |
+
+**Collision handling.** When two Steps' Generation chains resolve to
+the same GatewayRequest (`Step.ssot__GenerationId__c` collisions at the
+upstream DMO), first-step-wins: the earlier Step in walk order claims
+the GW. Subsequent Steps get `"gateway_request": null` with an adjacent
+`"gateway_request_collision": true` marker on the Step view, so readers
+can see why the GW is absent. The session-level
+`counts.gw_binding.declared_collisions` integer tracks the aggregate.
+On observed data this is 0; non-zero values indicate a real defect in
+the upstream DMO writers.
+
+### 2.6 Moment placement
+
+`session.moments[]` lives at the root of the session, not nested under
+`Interaction`. Each moment carries `interaction_ids[]`, a sorted list
+derived from `MomentInteraction` (the junction table). Rationale: the
+schema supports many-to-many (one moment can span multiple
+interactions; one interaction can belong to multiple moments), even
+though observed live data is 1:N. Nesting under Interaction would
+duplicate rows.
+
+Moments are absent on orgs without Agent Optimization enabled; the
+assembler never requires their presence.
+
+### 2.7 1:1 audit chain invariant
+
+For every `GatewayRequest` in the session, exactly one
+`GatewayResponse` exists (in live data, modulo in-flight calls at
+fetch time). `counts.audit_chain_1to1_ok` is `true` iff
+`len(gateway_requests) == len(gateway_responses)`. Drift is flagged in
+the counts block but does not crash the assembler — a caller
+re-fetching during an active session can still produce a partial tree.
+
+Note: this is Req↔Resp 1:1, not Req↔LLM_STEP. The typical session has
+more GatewayRequests than LLM_STEPs because prompt-template /
+plannerservice calls emit GatewayRequest rows without owning Step rows.
+
+### 2.8 `session_shape` enum
+
+Lifted verbatim from `dc._session_manifest.json.session_shape` into
+`dc._session_tree.json counts.session_shape`. Six values, classified
+by `fetch_dc.py` after the 5-wave waterfall; rules evaluated
+top-to-bottom, first match wins:
+
+| Value | Rule | Added |
+|---|---|---|
+| `session_not_found` | `sessions.json` returned 0 rows (bad sid or STDM not yet materialized) | original |
+| `interactions_not_materialized_yet` | sessions row present, but interactions/steps/messages all 0 (fresh session — STDM hierarchy hasn't materialized yet, but gateway_requests may exist) — assembler takes the gateway-direct path; see §2.9 | |
+| `gateway_requests_dropped_by_stdm` | DC `gateway_requests == 0` while runtime telemetry outside Data Cloud confirms ≥1 LLM call for the session — i.e. the STDM exporter has dropped writes the platform did emit. Distinct from `planner_ran_no_gateway_logs` (which means logging disabled at the source). This skill cannot disambiguate this state by itself; the operator must check runtime telemetry to reclassify. | |
+| `abandoned_before_llm` | steps > 0, LLM_STEP count == 0, gw_reqs == 0 (user typed, planner didn't reach an LLM call) | original |
+| `planner_ran_no_gateway_logs` | LLM_STEP > 0 AND steps_with_generation_id > 0 AND gw_reqs == 0 (Trust Layer gateway logging disabled; extra guard prevents misclassification from broken generations-IN clauses) | original |
+| `complete` | everything else (the "normal" bucket, including partial chain-orphan sessions) | original |
+
+The enum names only the operator-actionable states. For finer shape,
+read `counts.gw_binding`: if `declared == 0` but `gateway_requests > 0`,
+the session relied entirely on prompt-template / Flow-invoked LLM
+calls — normal but worth noticing.
+
+`gateway_requests_dropped_by_stdm` is the only shape that this skill
+cannot definitively classify on its own — disambiguating from
+`planner_ran_no_gateway_logs` requires a runtime telemetry probe
+outside Data Cloud. In this skill the session is reported as
+`planner_ran_no_gateway_logs`; the operator with access to the
+platform's runtime LLM-gateway telemetry can check for a matching
+gateway-call event to distinguish a real STDM exporter defect from
+"logging genuinely disabled at the source."
+
+### 2.9 Output: `dc._session_tree.json` schema
+
+Root shape:
+
+```jsonc
+{
+ "session": {
+ "id": "<sid>",
+ "_schema_version": 1, // see §2.9b
+ "identity": { ... }, // see §2.9a
+ "org": { "alias": "...", "instance_url": "..." },
+ "start_ts": "...",
+ "end_ts": null, // null while active
+ "end_type": "Completed | Abandoned | ...",
+ "channel": "...",
+ "participants": [
+ { "participant_id": "...", "role": "USER | AGENT",
+ "agent_api_name": "<null for USER>",
+ "agent_version": "...", "agent_type": "..." }
+ ],
+ "moments": [
+ { "moment_id": "...",
+ "agent_api_name": "...", "agent_version": "...",
+ "request_summary_text": "...", "response_summary_text": "...",
+ "interaction_ids": ["..."], // [] if no bridging rows; never omitted
+ "start_ts": "...", "end_ts": "...",
+ "tag_associations": [ ... ] // moment-scope only
+ }
+ ],
+ "interactions": [
+ {
+ "id": "...", "type": "TURN | SESSION_END", "topic": "...",
+ "trace_id": "...", // primary column or extracted from AttributeText
+ "start_ts": "...", "end_ts": "...",
+ "messages": [
+ { "message_id": "...", "type": "Input | Output",
+ "role": "USER | AGENT", // derived via participant join
+ "participant_id": "...", "text": "...",
+ "content_type": "...", "modality": "...", "ts": "..." }
+ ],
+ "telemetry_spans": [ ... ], // usually []
+ "steps": [
+ {
+ "id": "...",
+ "type": "LLM_STEP | ACTION_STEP | TOPIC_STEP | TRUST_GUARDRAILS_STEP | SESSION_END",
+ "name": "...",
+ "start_ts": "...", "end_ts": "...",
+ "error_text": null, // NOT_SET → null
+ "generation": { // present iff ssot__GenerationId__c != NOT_SET
+ "generation_id": "...",
+ "response_id": "...",
+ "response_text": "...", "masked_response_text": "...",
+ "feature": "...",
+ "quality": [ ... ], // ContentQuality rows parented on generationId__c
+ "categories": [ ... ], // ContentCategory rows parented on generationId__c
+ "feedback": [
+ { "feedback_id": "...", "feedback": "UP | DOWN", "action": "...",
+ "details": [ ... ], "records": [ ... ] }
+ ]
+ },
+ "gateway_request": { // present only when declared chain resolves
+ "binding_method": "declared",
+ "gateway_request_id": "...",
+ "feature": "...", "model": "...", "provider": "...",
+ "prompt_template_dev_name": "...", // "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0,
+ "prompt_text": "...", // raw input prompt
+ "response": { ... },
+ "tags": [ ... ], "records": [ ... ],
+ "metadata": [ ... ], "llm": []
+ },
+ "gateway_request_collision": true // present only when a prior step
+ // claimed this step's declared GW;
+ // gateway_request is null in this case
+ }
+ ],
+ "timestamp_bound_gateway_calls": [ // chain-orphans placed by ts-window
+ { "binding_method": "timestamp_window",
+ "bound_to_step_id": "...", // null if bound to Interaction, not a Step
+ "gateway_request_id": "...", "feature": "...", "model": "...",
+ "response": { ... }, "tags": [...], "records": [...],
+ "metadata": [...], "llm": [] }
+ ],
+ "tag_associations": [ ... ] // interaction-scope only
+ }
+ ],
+ "session_tag_associations": [ ... ], // session-scope only
+ "unbound_gateway_calls": [ // chain-orphans with no window match
+ { "binding_method": "unbound", "gateway_request_id": "...", /* ... */ }
+ ],
+ "counts": {
+ "interactions_total": 0, "interactions_turn": 0, "interactions_session_end": 0,
+ "steps_total": 0,
+ "steps_by_type": { "LLM_STEP": 0, "ACTION_STEP": 0, "TOPIC_STEP": 0,
+ "TRUST_GUARDRAILS_STEP": 0, "SESSION_END": 0 },
+ "generations": 0,
+ "gateway_requests": 0, "gateway_responses": 0,
+ "gateway_metadata": 0, "gateway_llm": 0,
+ "gateway_records_grounded": 0, "gateway_records_feedback": 0,
+ "feedback": 0,
+ "audit_chain_1to1_ok": true,
+ "gw_binding": { "declared": 0, "timestamp_window": 0, "unbound": 0,
+ "declared_collisions": 0 },
+ "session_shape": "complete | abandoned_before_llm | planner_ran_no_gateway_logs | gateway_requests_dropped_by_stdm | interactions_not_materialized_yet | session_not_found",
+ "pk_collisions": [ ], // {dmo, key} records; first-write-wins applied
+ "parse_warnings": [ ] // dc.<name>.json files that failed to parse
+ }
+ },
+ "catalog": { // session-filtered, not full org vocabulary
+ "agents_observed": [ "..." ],
+ "tag_definitions": [ ... ],
+ "tag_definition_associations": [ ... ],
+ "tags": [ ... ]
+ },
+ "_doc": "Assembled from DATA_ROOT/<sid>/dc.*.json. See dc._session_manifest.json."
+}
+```
+
+**Polymorphic dispatch:**
+- `GenAIGtwyObjRecord.parent__c` — if in `gw_req_by_id` → attached as
+ `GatewayRequest.records[]` (grounded attachments); if in
+ `feedback_by_id` → attached as `Feedback.records[]`; else silently
+ dropped.
+- `GenAIContentCategory.parent__c` — if in `generations_by_id` →
+ attached as `Generation.categories[]` (non-TOXICITY detectors); if
+ in `quality_by_id` → nested under the Quality row as
+ `_toxicity_subcategories[]`; else silently dropped.
+- `GenAIAiAgentTagAssociation` — routed by which of the three scope FKs
+ (`SessionId`, `InteractionId`, `MomentId`) is populated. Rows with
+ none are silently dropped.
+
+**Polymorphic dispatch failures are silent by design.** If these id
+spaces collide in future (they don't today — `gatewayRequestId__c`,
+`feedbackId__c`, `generationId__c`, and `quality.id__c` are all
+distinct UUID namespaces), the first-branch-wins behavior records the
+defect nowhere. Revisit if a real org ever shows a cross-namespace id.
+
+#### 2.9a `session.identity` sub-object
+
+Harvested from already-fetched rows. Fields that require values absent
+from every observed DMO row come out as `null`. Every string harvested
+from `tagValue__c` is piped through `html.unescape()` → quote-strip →
+`_clean()` to coerce `""`/`NOT_SET`/`UNSET_VALUE` to `None`.
+
+| Field | Source DMO | Source column / lookup |
+|---|---|---|
+| `org_id` | gateway_requests | `orgId__c`, first non-null after sort |
+| `platform_user_id` | gateway_requests | `userId__c`, first non-null after sort |
+| `planner_id` | gateway_requests | `plannerId__c`, first non-null after sort |
+| `bot_version_id` | gateway_requests | `botVersionId__c`, first non-null after sort |
+| `app_type` | gateway_requests | `appType__c`, first non-null after sort |
+| `bot_id` | gateway_request_tags | `tagValue__c` where `tag__c == "bot_id"` |
+| `bot_name` | gateway_request_tags | `tagValue__c` where `tag__c == "bot_name"` |
+| `agent_api_name` | gateway_request_tags | `tagValue__c` where `tag__c == "agent_developer_name"` (no fallback; MyAgent has no developer-name tag — look at `bot_name` + `agent_label` instead) |
+| `agent_label` | gateway_request_tags | `tagValue__c` where `tag__c == "agent_label"` |
+| `agent_version` | gateway_request_tags | `tagValue__c` where `tag__c == "agent_version_api_name"`, fallback `"version_api_name"` |
+| `agent_type` | gateway_request_tags | `tagValue__c` where `tag__c == "agent_type"` |
+| `planner_name` | gateway_request_tags | `tagValue__c` where `tag__c == "planner_name"` |
+| `planner_type` | gateway_request_tags | `tagValue__c` where `tag__c == "planner_type"` |
+| `configured_model` | gateway_request_tags | `tagValue__c` where `tag__c == "configured_model_name"` |
+| `messaging_session_id` | sessions[0] | `ssot__RelatedMessagingSessionId__c` |
+| `messaging_end_user_id` | participants | `ssot__ParticipantId__c` on the first USER-role row (sorted by `ssot__Id__c`) |
+| `voice_call_id` | sessions[0] | `ssot__RelatedVoiceCallId__c` |
+| `individual_id` | sessions[0] | `ssot__IndividualId__c` |
+| `bootstrap_variables` | sessions[0] | parsed from `ssot__VariableText__c` — channel-specific bootstrap key→value dict (e.g. `__resolved_locale__`, `__supports_result_display__`); empty `{}` when the column is null/empty/unparseable |
+| `mode` | derived | one of `production_messaging` / `builder_previewer` / `voice` / `unknown` — derived from `(channel, RelatedMessagingSessionId__c, RelatedVoiceCallId__c, bootstrap_variables.keys)`. See `_derive_mode` + `_BUILDER_PREVIEWER_INDICATOR_KEYS` in `assemble_dc.py`. |
+
+**Sorting (required for idempotence):**
+- `gateway_requests` — sort by `(timestamp__c, gatewayRequestId__c)`
+ ascending, then take first non-null.
+- `gateway_request_tags` — sort by `(parent__c, tag__c, tagValue__c)`
+ ascending, then filter by tag name and take first non-null.
+- `participants` — sort by `ssot__Id__c` ascending, then take the first
+ USER-role row.
+- `sessions[0]` — by contract, one row per session; no sort needed.
+
+**Trimmed fields:** `user_location`, `user_context` are not promoted
+(low debugging value, opaque without a decoder ring).
+
+**Minimal tree exclusion.** The session-not-found short-circuit path
+(§2.11) does **not** emit an `identity` sub-object — identity
+harvesters need non-empty gateway rows, which are guaranteed empty in
+this branch. Renderer's minimal branch handles absent identity
+gracefully.
+
+#### 2.9b `session._schema_version`
+
+Current value: `1`. Emitted on both the full tree and the minimal
+session-not-found tree. Additive changes (new sub-objects, new fields)
+do NOT bump this. Breaking changes (rename or remove a top-level key,
+change the shape of `interactions[]`, etc.) bump it.
+
+Renderer refuses to render a tree with an incompatible version; see
+§3.10.
+
+### 2.10 Idempotence
+
+Running the assembler N times on the same `DATA_ROOT/<sid>/` produces
+a byte-identical `dc._session_tree.json`. Rules:
+
+- Arrays sort by source timestamp ascending; on ties, by primary-key
+ string.
+- Any set-derived array (`agents_observed`, `interaction_ids[]`, etc.)
+ is emitted via `sorted(...)` before serialization.
+- `json.dumps(..., sort_keys=True)` for all dict output.
+- Identity harvest uses the explicit sort keys in §2.9a for
+ first-non-null picks.
+- Verified on the live test fixture: `diff` of two runs returns empty.
+
+### 2.11 Session-not-found short-circuit
+
+If `sessions.json` returned 0 rows, the assembler writes a minimal
+tree with only `session.id`, `session.org`,
+`session._schema_version: 1`, and
+`counts.session_shape = "session_not_found"`. No `identity`, no
+`interactions[]`, no `catalog{}`.
+
+---
+
+## 3. Render stage
+
+`scripts/render_dc.py` turns `dc._session_tree.json` into a human
+markdown file.
+
+### 3.1 Purpose + scope
+
+**Input:** `dc._session_tree.json` + `dc._session_manifest.json` (the
+latter only for the Empties diagnostics section).
+
+**Output:** `dc._session_summary.md` — 11 top-level sections, with `Session bootstrap` and `Planner LLM calls` conditionally suppressed (see §3.3).
+
+**Contract:** pure tree reader. No DMO loads. No fetches. Everything
+the renderer displays either lives directly on `tree.session.*` or is
+composed from tree fields in the renderer's presentation layer.
+
+### 3.2 Inputs
+
+- `dc._session_tree.json` — primary input. Renderer SystemExits with a
+ clear "tree not found" message if absent.
+- `dc._session_manifest.json` — consulted for the Empties diagnostics
+ section. If absent, that section renders empty.
+
+The 24 raw `dc.<name>.json` artifacts are NOT loaded by the renderer.
+
+### 3.3 Output: section order
+
+The full-tree branch emits these top-level sections in order. The
+gateway-direct branch (§2.8 `interactions_not_materialized_yet`) and
+the minimal session-not-found branch use abbreviated section sets;
+see `_render_gateway_direct` / `_render_minimal` in `render_dc.py`.
+
+1. `## Session identity` — identity fields from `tree.session.identity`
+ plus display-only cells (Agent, Total duration) composed in-renderer.
+2. `## Session bootstrap` — channel mode + bootstrap variables
+ (`identity.mode`, `identity.bootstrap_variables`). Surfaces these to
+ make MIAW vs Builder Previewer distinguishable at-a-glance —
+ `ssot__AiAgentChannelType__c` alone collides between the two. Section
+ is suppressed (not rendered) when both `mode` and `bootstrap_variables`
+ are absent — backwards-compat with older trees.
+3. `## ID reference` — full UUIDs for everything truncated in the
+ hierarchical trace.
+4. `## Transcript` — USER ↔ AGENT narrative per TURN interaction.
+ SESSION_END interactions have no messages and are skipped.
+5. `## Complete hierarchical trace` — Interaction → Step → Generation →
+ GatewayRequest, with `+start + duration = +end` math on Interaction
+ and Step lines. Single timestamps on Generation and GatewayRequest
+ (no computed latencies; see §3.6). UUIDs truncated to 8 chars + `…`;
+ full forms in §2 above.
+6. `## Per-turn summary` — one row per interaction.
+7. `## Planner LLM calls (full prompts + responses)` — **opt-in via
+ `--show-prompts`; suppressed by default**. Walks `interactions[].steps[]`, builds one
+ `#### LLM call N — <short-id>` block per step that has a
+ `gateway_request`. Renders the full input prompt (from
+ `gateway_request.prompt_text`) and full response (from
+ `generation.response_text`, HTML-unescaped) inside fenced code
+ blocks. Per-payload display capped at 64 KB; full payloads always
+ remain authoritative on disk in `dc.gateway_requests.json` /
+ `dc.generations.json`. Off by default because multi-turn sessions
+ with 30 KB+ prompts would dominate the summary.
+8. `## Visual analysis` — gantt + LLM-call overlay.
+9. `## Session counts` — engineer-facing table of manifest counts.
+10. `## Empties diagnostics` — one row per DMO with `rows == 0` and a
+ populated `_unavailable_reason` lifted verbatim from the manifest.
+11. `## Catalog (session-filtered)` — TagDefinitions /
+ TagDefinitionAssociations / Tags filtered to agents observed in the
+ session.
+
+DC alone does not expose per-turn LLM latency in a useful form, so this
+skill emits no `## Latency rollups` section. Generation and
+GatewayRequest carry single-write timestamps (see §3.6); they are not
+start/end pairs.
+
+### 3.4 Ellipsis rule
+
+In the `## Complete hierarchical trace`:
+
+- All UUIDs (interaction_id, step_id, generation_id,
+ gateway_request_id) render as the first 8 characters followed by `…`.
+- Full UUIDs live in the `## ID reference` table above, keyed by the
+ same 8-char prefix.
+
+This keeps the trace scannable while preserving the ability to
+cross-reference by ID.
+
+### 3.5 Session-end derivation
+
+`session.end_ts` can be null for two reasons:
+
+1. The session is still active.
+2. The session ended but STDM hasn't materialized the `end_ts` column
+ yet.
+
+Renderer display rule: if `session.end_ts` is non-null, render it
+directly with `✓ materialized` suffix. If null, look at the last
+interaction by timestamp:
+
+- If a SESSION_END interaction exists, use its `start_ts` as the
+ derived end with `from SESSION_END interaction` suffix.
+- Otherwise, use the last TURN interaction's `end_ts` (or `start_ts`
+ if its end is null) with `session still open (last TURN)` suffix.
+
+The derivation is display-only; the tree's `session.end_ts` is not
+modified.
+
+### 3.6 Why we don't compute latencies on generation/gateway_request
+
+`Generation.timestamp__c` and `GatewayRequest.timestamp__c` are
+single timestamps representing when the DC row was written. They are
+NOT `start_ts`/`end_ts` pairs. Treating the delta between two of them
+as a "latency" is misleading — the gap reflects how DC serialized the
+audit, not how long the LLM call took.
+
+Interaction and Step DMOs DO expose start_ts + end_ts pairs; the
+renderer computes `+offset + duration = +end` math for those.
+
+### 3.7 Empties diagnostics
+
+Walk `manifest["queries"]` for entries with `rows == 0` and a
+populated `_unavailable_reason`. Render each as a row:
+`| <dmo_name> | <rows> | <verbatim reason> |`. The renderer does not
+infer reasons.
+
+Artifacts that failed to parse go into `tree.counts.parse_warnings` and
+surface in the `## Session counts` section, not here.
+
+### 3.8 Idempotence
+
+Running `render_dc.py --session <sid>` N times on the same
+`dc._session_tree.json` produces a byte-identical
+`dc._session_summary.md`. Rules:
+
+- All section builders walk tree arrays in the order the tree provides
+ them; the tree itself is already sorted.
+- No timestamps of "now" embedded in the output.
+- No set-derived ordering; any set-to-list conversion goes through
+ `sorted(...)`.
+- Verified on the live test fixture: `diff` of two runs returns empty.
+
+### 3.9 Session-not-found short-path
+
+If the tree has `_schema_version: 1` but no `interactions[]` key, the
+renderer emits a minimal markdown file:
+
+```markdown
+# Session <sid>
+
+## Session identity
+
+| Field | Value |
+|---|---|
+| Session id | <sid> |
+| Session shape | session_not_found |
+
+_No interactions resolved in Data Cloud. Check the session id, or
+wait for STDM materialization._
+```
+
+No transcript, no trace, no counts, no catalog.
+
+### 3.10 Tree schema version check
+
+First check in `main_for_session()`:
+
+- `tree.session._schema_version == 1` → render.
+- `tree.session._schema_version` missing → stderr WARN, render anyway
+ (treat as best-effort for older trees).
+- Any other value → `SystemExit("render_dc: unsupported tree
+ _schema_version=<v>; expected 1")`. Refuses rather than risking a
+ silent schema mismatch.
+
+---
+
+## 4. Reading order for a new skill author
+
+1. Read this file (contract).
+2. Run the pipeline once against a fresh session: `python3
+ scripts/fetch_dc.py --session <sid> --org <alias>`. Inspect
+ `DATA_ROOT/<sid>/` — you get the 24 `dc.<name>.json`, the manifest,
+ the tree, and the summary.
+3. Open `dc._session_tree.json` and trace the declared chain for one
+ LLM_STEP end-to-end.
+4. Read the matching `dc._session_summary.md`.
+5. Read `scripts/assemble_dc.py` (module docstring points back here),
+ then `scripts/render_dc.py`.
+6. Cross-reference [`dc_dmo_fields.md`](./dc_dmo_fields.md) when you
+ hit a field whose origin is unclear.

package/skills/agentforce-d360-analyze/scripts/_shared/__init__.py

@@ -0,0 +1,2 @@
+# Shared module for the investigating-agentforce-d360 skill.
+# Three siblings live in this package: paths, fs_guard, sql.