@salesforce/afv-skills 1.22.0 → 1.24.0

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

@@ -1,608 +0,0 @@
-# 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/investigating-agentforce-d360/scripts/_shared/__init__.py

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