# Artifacts And Reports

<!-- BEGIN GENERATED: guide-map -->
## Guide map

Read only the section needed for the next decision. Line ranges are exact
for this generated runtime target.

| Section | What it covers | Lines |
| --- | --- | --- |
| [Purpose](#purpose) | Scope, ownership, and the central operating question. | 31-43 |
| [Use This When](#use-this-when) | Tasks and conditions that belong in this guide. | 44-48 |
| [Do Not Use This For](#do-not-use-this-for) | Boundaries and the correct routes for excluded work. | 49-58 |
| [Mental Model](#mental-model) | Concepts and state boundaries needed for correct operation. | 59-81 |
| [Choose A Path](#choose-a-path) | Decision hierarchy for selecting the right capability or provider. | 82-90 |
| [Primary SDK Paths](#primary-sdk-paths) | Operating guidance and contracts for this section. | 91-102 |
| [Supporting References](#supporting-references) | Capability, provider, policy, and runtime guides for this outcome. | 103-115 |
| [Preflight](#preflight) | State, authority, inputs, and readiness to verify before execution. | 116-131 |
| [Risk And Side Effects](#risk-and-side-effects) | Effects, approvals, cost, privacy, and retry boundaries. | 132-144 |
| [Canonical Operating Pattern](#canonical-operating-pattern) | The normal end-to-end execution sequence. | 145-166 |
| [Core SDK Surfaces](#core-sdk-surfaces) | Exact source-backed callable contracts owned by this guide. | 167-174 |
| [Data Contracts](#data-contracts) | Required identities, fields, evidence, handles, and durable shapes. | 175-201 |
| [Verification](#verification) | Evidence required before reporting success. | 202-216 |
| [Troubleshooting](#troubleshooting) | Failure diagnosis and corrective routes. | 217-227 |
| [Related References](#related-references) | Adjacent boundaries and when to cross them. | 228-237 |
<!-- END GENERATED: guide-map -->

Create, inspect, verify, publish, and share durable CSV, HTML, report, and rowset
outputs.

## Purpose

Artifacts And Reports owns the final deliverable contract. It turns produced
rows, files, and visualizations into durable, verifiable objects that teammates
can inspect and share without depending on the originating agent session.

The central rule is one immutable artifact identity for one producing source
or declared output. Exact byte digests deduplicate content inside the
organization, so distinct outputs may share the same blob without becoming the
same artifact. CSV, HTML, Slack, browser, Play, and download experiences are
projections of the canonical artifact, not separate copies with independent
truth.

## Use This When

Use this guide when the deliverable itself matters. Provider-job polling is one
supporting lifecycle, not the user outcome.

## Do Not Use This For

| Task | Owning Reference |
| --- | --- |
| Acquiring or enriching the underlying companies or contacts | The matching search or enrichment outcome guide |
| Polling a provider job when no final deliverable is requested | `artifacts_jobs.md` |
| Publishing or sending a sequence | `outbound-campaigns.md` |
| Operating or repairing a durable Play | `workflows.md` |
| Treating raw logs, browser captures, or previews as a finished deliverable | The producing runtime guide, then this guide once final bytes exist |

## Mental Model

Separate four layers:

1. The semantic result defines which entities qualify and why.
2. The representation encodes that result as rows, CSV, HTML, images, PDF, or
   another requested media type.
3. The canonical artifact binds the producing source to exact bytes, immutable
   presentation, provenance coordinates, and integrity evidence.
4. Projections make that artifact visible in Slack, the browser, a Play, or a
   download without creating another source of truth.

A preview is evidence about a subset. It is not the final artifact. A report is
not correct merely because it renders; its labels, metrics, tables, and links
must agree with the final underlying result.

For a Workflow Play, keep the related identities connected without collapsing
them. The code revision is the immutable executable input. The schedule and
tick pin that revision. The run and checkpoint record execution. Each declared
output becomes one immutable artifact. The run-output association binds that
artifact to the execution. Slack, browser, Play, and download surfaces then
project the same committed artifact version.

## Choose A Path

1. Choose the semantic deliverable and its membership predicate.
2. Use CSV for interoperable row data, HTML or reports for rich review, and
   durable artifacts for large or asynchronous outputs.
3. Give every produced output one canonical artifact identity. A multi-file
   output has one entrypoint and an immutable manifest. Slack, browser, Play
   UI, and download links are projections of those same bytes.

## Primary SDK Paths

<!-- BEGIN GENERATED: primary-sdk-paths -->
| Primary function | Choose it when | Required inputs | Returns | Exact contract |
| --- | --- | --- | --- | --- |
| `vf.jobs.result` | Use after an asynchronous SDK start call to wait, page rows, inspect the resulting artifact, or stage it without re-deriving lifecycle control flow. | `job_or_id` | `job_result_handle` | [`artifacts_jobs.md`](artifacts_jobs.md) · installed SDK: `verbiflow/jobs.py:939-975` |
| `vf.artifacts.inspect` | Use to verify an existing durable artifact's schema, counts, sample rows, provenance, and warnings before delivery or reuse. | `artifact_id` | `artifact_inspection` | [`artifacts_jobs.md`](artifacts_jobs.md) · installed SDK: `verbiflow/artifacts.py:293-341` |
| `vf.artifacts.export_csv` | Use when an existing durable row artifact must become an exact local CSV file. | `artifact_id`, `output_path` | `artifact_csv_export` | [`artifacts_jobs.md`](artifacts_jobs.md) · installed SDK: `verbiflow/artifacts.py:396-456` |
| `vf.reports.render` | Use when verified rows need an editable local Play report with HTML, data sidecars, source, and provenance. | `output_dir`, `report` | `report_render` | [`workflow_reports.md`](workflow_reports.md) · installed SDK: `verbiflow/reports.py:1302-1414` |
| `vf.artifacts.publish` | Use when one completed local CSV, HTML, Markdown, PDF, text, JSON, image, audio, video, archive, or other file must become a canonical team-shareable artifact. | `file_path` | `canonical_artifact_receipt` | [`artifacts.md`](artifacts.md) · installed SDK: `verbiflow/artifacts.py:59-186` |
<!-- END GENERATED: primary-sdk-paths -->

## Supporting References

Open only the child that resolves the next material decision.

| Reference | Use it for | Kind |
| --- | --- | --- |
| [`artifacts_jobs.md`](artifacts_jobs.md) | Durable artifact paging, job polling, cancellation, and export handles. | capability |
| [`csv_output.md`](csv_output.md) | Final CSV shape, field quality, provenance, and delivery contract. | capability |
| [`dashboard.md`](dashboard.md) | Standalone self-contained HTML dashboards and visualizations. | capability |
| [`row_operations.md`](row_operations.md) | Deterministic row transforms, joins, and reviewable LLM qualification or annotation with rationale and confidence. | capability |
| [`workflow_reports.md`](workflow_reports.md) | Editable Play reports, HTML outputs, and reviewable score, rationale, confidence, and evidence presentation. | capability |
| [`testing.md`](testing.md) | Semantic verification for rows, artifacts, Play outputs, reports, and effects. | policy |

## Preflight

Before producing the deliverable, establish:

- the user-facing question and the membership predicate for every output;
- the intended audience, review context, and sharing boundary;
- the canonical row identity and required fields;
- the output format, media type, filename, and expected size;
- whether multiple files express the same rows or independently qualified
  results;
- the source, observation time, and lineage that must remain inspectable;
- the durable owner, such as one-off artifact or a declared Play output.

If two requested lists could differ, define and evaluate their predicates
independently even when they happen to contain identical rows.

## Risk And Side Effects

| Operation | Risk And Boundary |
| --- | --- |
| Local transforms and draft rendering | Local work. Avoid overwriting the only copy of source evidence. |
| Provider-backed qualification or large artifact jobs | Credit-consuming asynchronous work. Preserve handles and bound execution. |
| Uploading or publishing an artifact | Reversible platform write. Verify identity, bytes, and access scope. |
| Sharing a link or posting in Slack | Customer-visible projection. Confirm the intended organization and audience. |

Large artifacts can leak sensitive rows into logs or conversation context.
Inspect bounded samples and aggregates, keep complete data in the artifact, and
never print secrets or raw credential material into the deliverable.

## Canonical Operating Pattern

1. Define the semantic predicate and final schema for each output.
2. Produce the complete result from the canonical source execution.
3. Normalize and validate rows before choosing presentation details.
4. Render the requested representations from the same verified result or from
   explicitly independent predicates.
5. Persist exact bytes and bind them to one durable artifact identity each.
6. Create the required browser, Play, Slack, or download projections from those
   identities.
7. Re-read the exact persisted bytes and verify the projections before claiming
   completion.

Inside a Workflow Play, declare final outputs on the workflow before it runs.
Use `workflow.declare_output(...)` for CSV, HTML, Markdown, JSON, PDF, text,
image, audio, video, archive, or other files. `WorkflowResult.to_json()` carries
the same declaration envelope returned by Hosted execution. The run definition
persists it across process boundaries.
A later Local `vf.workflows.snapshot(...)` or `vf.workflows.sync(...)` may
publish the exact declared bytes from an eligible completed Local run.
Do not invent a host-only deliverable payload or upload a second copy for Slack.

## Core SDK Surfaces

<!-- BEGIN GENERATED: core-sdk-surfaces -->
| Function | Use When | Inputs | Output And Handles To Preserve | Side Effect | Source |
| --- | --- | --- | --- | --- | --- |
| `vf.artifacts.publish` | Use after verifying a completed local file when it must become one immutable, organization-scoped artifact with a stable team page, exact content/download links, and a reusable hosted-agent attachment id. | <strong>Required</strong>: `file_path` (str \| Path; required): Absolute local file path.<br><strong>Optional</strong>: `alt_text` (str \| None; optional; default `None`): Alt text parameter for `artifacts.publish`.; `description` (str \| None; optional; default `None`): Human-readable description for the created resource.; `kind` (text \| markdown \| html \| csv \| json \| image \| audio \| video \| pdf \| archive \| file; optional; default `'file'`): Allowed values: text, markdown, html, csv, json, image, audio, video, pdf, archive, file.; `media_type` (str \| None; optional; default `None`): Media type parameter for `artifacts.publish`.; `ordinal` (int; optional; default `0`): Ordinal parameter for `artifacts.publish`.; `request_id` (str \| None; optional; default `None`): Stable publication identity for explicit retry control.; `title` (str \| None; optional; default `None`): Title parameter for `artifacts.publish`. | `dict` with canonical `artifact_id`, reusable `attachment_id`, authenticated team `artifact_href`, exact `content_href` and `download_href`, filename, media type, byte size, SHA-256 digest, and manifest digest.<br><strong>Common next calls</strong>: `vf.workflows.sync` | platform_write | installed SDK: `verbiflow/artifacts.py:59-186` |
<!-- END GENERATED: core-sdk-surfaces -->

## Data Contracts

Every durable artifact should preserve:

| Field | Meaning |
| --- | --- |
| Artifact identity | Stable organization-scoped identifier for the producing source or declared output. |
| Integrity | Byte size and cryptographic digest for the persisted content. |
| Representation | Media type, filename, format, and optional entrypoint. |
| Semantics | Output label, membership predicate, schema, row count, and stable row key in the owning result or report contract. |
| Provenance | Producing run, source or job handles, observation time, and limitations in canonical source coordinates or the owning result contract. |
| Projection | Share or delivery references that resolve back to the same artifact identity. |

Use `vf.sdk.describe("workflow.declare_output")` for the exact installed
signature and source span. A file declaration uses `path=...`. HTML uses one
`entrypoint=...` plus its immutable `assets=(...)`. Small text or Markdown may
use inline `content=...`; inline declarations do not accept `row_count`.
`assets=(...)` is HTML-only. Paths are normalized project-relative paths and
must refer to bytes produced by the terminal run. Snapshot and sync fail when a
declared file is missing or escapes the Play root. Inline declarations share a
768 KiB aggregate result-envelope budget; use files for larger content.

For related outputs, preserve an explicit relationship instead of relying on
matching filenames. HTML summaries should identify the row artifact they
summarize; downloadable tables should identify the report or Play output that
exposes them.

## Verification

Inspect representative rows and cross-artifact relationships. Verify schema,
membership, provenance, exact final bytes, durable ID, and shareable projection.

Also verify that labels and counts mean what they say, links resolve under the
intended member authority, and every projection serves the persisted version
rather than a stale local draft.

For a scheduled Play, verification is complete only when the pinned code
revision, terminal tick, Play run, declared output association, immutable blob
version, and requested delivery projection all resolve. A retry must adopt the
same publication receipt instead of rerunning completed provider or browser
work.

## Troubleshooting

| Symptom | Likely Cause | What To Do |
| --- | --- | --- |
| Preview looks correct but download is incomplete | Preview rows were treated as the final result | Page or export the complete artifact and verify final row count and digest. |
| HTML count differs from CSV | Representations were rendered from different states | Rebuild both from the same verified result or document separate predicates. |
| Link opens but a teammate cannot access it | Projection scope or member authority is wrong | Inspect the artifact's organization and sharing projection; do not duplicate the file. |
| Slack attachment differs from the browser artifact | Delivery uploaded separate bytes | Project the canonical artifact instead of rebuilding at delivery time. |
| Report renders with empty sections | Schema or view bindings do not match final rows | Inspect required fields and representative final rows before rerendering. |
| Artifact exists but provenance is missing | Bytes were uploaded outside the producing run contract | Bind the artifact to its source run, job, or Play output before handoff. |

## Related References

| If You Are Doing This | Read Next |
| --- | --- |
| Paging, waiting, cancellation, or export handles | `artifacts_jobs.md` |
| Deterministic row shaping and joins | `row_operations.md` |
| CSV schema and field quality | `csv_output.md` |
| Standalone HTML dashboards | `dashboard.md` |
| Declared Play report outputs | `workflow_reports.md` |
| Semantic and cross-artifact proof | `testing.md` |
