@paradigma-inc/flywheel 0.1.16 → 0.1.19

package/skills/flywheel-auto/references/ARTIFACTS.md

@@ -1,218 +1,49 @@
 # Flywheel Artifacts
 
-Canonical reference for node artifact publishing in Flywheel MCP 0.9.
-
-Legacy note:
-
-- historical `run_artifacts` rows are retained for backward reads.
-- new artifact writes must use the MCP batch upload workflow:
-  `flywheel_prepare_artifact_uploads` -> raw file upload(s) ->
-  `flywheel_finalize_artifact_uploads`.
-
-## Node MCP Contract
-
-Artifacts are managed through node MCP tools:
-
-- `flywheel_prepare_artifact_uploads` prepares one or more signed raw-file
-  upload requests for a node.
-- The caller executes each returned upload request with raw bytes.
-- `flywheel_finalize_artifact_uploads` appends all staged uploads in that batch
-  to the node and bumps node revision once.
-- `flywheel_list_artifacts` and `flywheel_get_artifact` return artifact
-  metadata.
-- `flywheel_get_artifact_preview` reads persisted preview payload content by
-  artifact id.
-- `flywheel_commit_node` commits/finalizes node state after terminal fields are
-  already staged.
-
-Contract rules:
-
-- `flywheel_prepare_artifact_uploads` requires `expected_revision` and enforces
-  optimistic locking before issuing upload tickets.
-- Upload uses the signed one-time ticket in each returned `upload_url`;
-  client-supplied path/reference fields are not part of this contract.
-- Raw upload only stages payloads. It does not mutate node state or bump node
-  revision.
-- `flywheel_finalize_artifact_uploads` is the single node mutation point for an
-  artifact batch.
-- `flywheel_commit_node` is finalize-only:
-  - request shape is `expected_revision` with optional `summary` override.
-  - node kind/outcome/hypothesis/insights/no_artifacts_reason must already be
-    staged.
-  - commit transitions lifecycle to `committed`.
-- committed node contract rules remain strict:
-  - `kind=empirical` + `outcome=completed` requires artifacts or
-    `no_artifacts_reason`.
-  - `kind=insight` requires non-empty `insights`.
-  - `kind=empirical` requires empty `insights`.
-- MCP mutating calls require idempotency:
-  - tool transport auto-manages idempotency keys for tool calls.
-  - direct HTTP callers must provide `Idempotency-Key` on mutating MCP
-    endpoints.
-
-`artifact_type=banner` is supported for campaign root visuals. It follows the
-same raw image upload validation path as `artifact_type=image` and is intended
-for zoomed-out canvas visibility.
-
-## Prepare Request Shape
-
-`POST /mcp/nodes/{node_id}/artifacts/uploads/prepare`
-
-```json
-{
-  "expected_revision": 7,
-  "items": [
-    {
-      "artifact_type": "image",
-      "title": "Loss curve",
-      "execution_id": "optional-execution-id",
-      "metadata": {
-        "source": "training-run"
-      },
-      "filename": "loss_curve.png",
-      "media_type": "image/png"
-    }
-  ]
-}
-```
-
-Notes:
-
-- `items` must contain at least one structured object item.
-- String or JSON-encoded item payloads are invalid at the tool boundary.
-- `filename` and `media_type` are required for each item.
-- `metadata` is caller-defined JSON.
-
-## Prepare Response Shape
-
-```json
-{
-  "batch": {
-    "batch_token": "uuid",
-    "expires_at": "2026-03-09T16:00:00+00:00",
-    "max_upload_bytes": 10485760,
-    "items": [
-      {
-        "upload_id": "uuid",
-        "upload_url": "https://.../mcp/artifacts/uploads/{upload_id}?ticket=...",
-        "method": "PUT",
-        "headers": {
-          "Content-Type": "image/png",
-          "X-Flywheel-Artifact-Filename": "loss_curve.png"
-        },
-        "curl_command": "curl -sS -X PUT '...' -H 'Content-Type: image/png' -H 'X-Flywheel-Artifact-Filename: loss_curve.png' --data-binary @/absolute/path/to/file"
-      }
-    ]
-  }
-}
-```
-
-## Raw Upload Step
-
-Execute each returned request exactly:
-
-- Method: `PUT`
-- URL: `batch.items[i].upload_url`
-- Body: raw file bytes
-- Headers:
-  - `Content-Type` (media type)
-  - `X-Flywheel-Artifact-Filename` (filename hint)
-
-A successful upload:
-
-- validates the uploaded bytes against the requested artifact type
-- stages canonical payload JSON in blob storage
-- returns `202 Accepted`
-- does not yet append an artifact record to the node
-
-## Finalize Request and Response
-
-`POST /mcp/nodes/{node_id}/artifacts/uploads/finalize`
-
-```json
-{
-  "batch_token": "uuid"
-}
-```
-
-Successful finalize:
-
-- validates the batch is complete and still revision-compatible
-- appends all staged artifacts to the node
-- persists canonical payload JSON to `artifacts/nodes/{node_id}/{artifact_id}.json`
-- bumps node revision once
-- returns `{ "node": ..., "artifacts": [...] }`
-
-## Artifact Preview Behavior
-
-Artifact preview endpoint:
-`GET /mcp/nodes/{node_id}/artifacts/{artifact_id}/preview`.
-MCP tool: `flywheel_get_artifact_preview`.
-
-- Preview reads canonical persisted payload blob (`storage_path`) only.
-- No workspace dependency or local-file fallback is required.
-- `data_url` in preview responses is render output only; never upload JSON
-  metadata wrappers.
-- Preview-normalized types:
-  - `image` -> image payload with `data_url`
-  - `html` / `plotly_html` -> HTML payload
-  - `json` -> JSON payload
-  - `text` / `diff_carousel` and common text/code extensions -> text payload
-
-## WebUI Artifact Payload Reads
-
-When artifacts are projected through node responses, the server returns
-normalized storage references for each artifact payload:
-
-- `storage_path`: canonical blob path (for example
-  `artifacts/nodes/{node_id}/{artifact_id}.json`).
-- `storage_url`: the single client/host read URL for that payload.
-  - All blob backends: `/blobs/{storage_path}` authenticated byte-serving
-    proxy after access checks.
-
-Clients should read artifact bytes from `storage_url` only. `storage_path`
-remains metadata/debug context and must not be reconstructed into fetch URLs by
-clients. Payload loads are coordinated through a shared loader with in-flight
-deduplication, cache reuse, and bounded fetch concurrency to avoid bursty
-request storms and `429` backpressure under artifact-heavy nodes.
-
-The node overview panel additionally avoids eager load spikes by defaulting to
-collapsed mode for artifact-heavy nodes and deferring artifact rendering until
-cards approach the viewport.
-
-## Artifact Load Telemetry
-
-The WebUI emits a batched first-party product analytics event,
-`web_artifact_payload_batch`, through `POST /analytics/events`.
-
-This event is intended for aggregate artifact read-path observability and
-includes fields such as:
-
-- load volume (`loads_started`, `loads_completed`, `loads_failed`)
-- rate-limit incidence (`loads_429`)
-- queue/load latency aggregates
-- source mix (`/blobs/*` authenticated proxy)
-- top per-node load/failure summaries in the batch window
-
-## File Inventory Surfaces
-
-Artifacts and attachments are exposed through two HTTP inventory endpoints:
-
-- `GET /users/me/files` for account-wide browsing in Settings.
-- `GET /nodes/{node_id}/files` for node lineage-scoped browsing in the node
-  details panel.
-
-Inventory entries include source context (`node_id`, `execution_id`) so the UI
-can jump directly to the originating node or execution.
-
-## Common Invalid Payload Causes
-
-- stale `expected_revision` at prepare or finalize time
-- missing/invalid upload ticket
-- expired upload ticket or batch
-- upload body exceeds configured size limit
-- uploaded bytes do not match requested artifact format (for example invalid
-  JSON)
-- finalize called before every prepared upload is staged
-- commit contract violations (for example empirical `completed` without
-  artifacts or `no_artifacts_reason`)
+Canonical artifact upload/finalize contract derived from `mcp_contract.py`.
+
+## Upload Contract
+
+- Prepare tool: `flywheel_prepare_artifact_uploads`.
+- Finalize tool: `flywheel_finalize_artifact_uploads`.
+- Raw file upload required between prepare/finalize: `True`.
+- Upload transport step: `PUT` to `prepare.items[].upload_url`.
+- Required headers source: `prepare.items[].upload_headers`.
+- Upload body contract: `raw_file_bytes`.
+- Prepare item required fields: `artifact_type`, `filename`, `media_type`.
+- Prepare item optional fields: `title`, `execution_id`, `metadata`, `note`.
+- Prepare item note: prepare.items[] is structured object input at the tool boundary; stringified JSON payloads are invalid.
+- Raw upload stage success code: `202`.
+- Stage semantics: `accepted_and_staged`.
+- Finalize appends the batch with a single revision bump: `True`.
+- Forbidden upload payload kinds: `json_metadata_wrapper`.
+- Optional note field `note` applies to `artifact_metadata_record` (markdown allowed: `True`).
+
+## Supported Artifact Types
+
+- `text`, `table`, `json`, `image`, `banner`, `html`, `plotly_html`, `vega`, `checkpoint`, `binary`, `diff_carousel`
+
+## Metadata Contract
+
+- `title` required non-empty: `True`.
+- Display label field: `title`.
+- Title normalization priority: `explicit_title` -> `payload.title` -> `payload.name` -> `basename(payload.path|payload.filename|payload.file)` -> `basename(filename)` -> `basename(storage_path)` -> `artifact_type` -> `artifact`.
+- Title must not derive from: `storage_url`.
+- `storage_url` purpose: `raw_artifact_byte_read_url`.
+- `storage_url` cannot be used as display label: `True`.
+
+## Preview and Read Contract
+
+- `flywheel_list_artifacts`: List node artifacts.
+- `flywheel_get_artifact`: Get one artifact by id.
+- No dedicated artifact preview tool exists in the current MCP operation catalog.
+- Guidance: use flywheel_prepare_artifact_uploads, raw-file upload, and flywheel_finalize_artifact_uploads to publish experiment evidence before empirical completed commits
+
+## Failure Causes to Handle Explicitly
+
+- Stale `expected_revision` on mutating calls returns `409` and requires explicit reconciliation.
+- Reusing an idempotency key with a different payload hash causes `409_conflict`.
+- Empirical `completed` commits must satisfy one of: `artifacts_non_empty`, `no_artifacts_reason_non_empty`.
+- Prepare item payloads must be structured objects; stringified JSON item payloads are invalid.
+- Uploading metadata wrappers instead of raw file bytes violates the upload contract.
+- Finalize requires a valid prepared batch token and staged uploads from that batch.