# PlatPhorm Trace v0.13.0
> Canonical observability spine, trace aggregation platform, span lifecycle system, async ingestion API, MCP trace observatory, W3C Trace Context layer, cross-site correlation engine, and AI execution microscope for PlatPhormNews.

## Truth Model
Every homepage metric is generated from /api/v1/observatory and includes value, source, sourceUrl, fetchedAt, state, and traceId when applicable.
Storage status: connected.

## Runtime Counts
- Sites tracked: 269
- Trusted domains: 269
- Pending sitemap domains: 0
- MCP endpoints tracked: 87
- Trace MCP tools: 79
- Trace MCP resources: 35
- Trace MCP prompts: 21
- Persisted traces: 1136
- Active traces: 2
- Persisted spans: 8304
- Storage: connected
- Integration statuses: observed 41, registered 228, degraded 0, unknown 0
- platphorm-* project coverage: total 143, observed 40, registered 76, degraded 0, repository-only 26, unmapped 0, ambiguous 1

## Auth
Public read-only discovery and public-safe trace summaries are open.
Mutating, ingestion, sync, replay, fork, workflow, reporting, and remediation actions require PLATPHORM_API_KEY.
Accepted protected headers:
- Authorization: Bearer $PLATPHORM_API_KEY
- X-PlatPhorm-API-Key: $PLATPHORM_API_KEY

## Canonical Sources
- Network graph: https://platphormnews.com/api/network/graph
- Sitemap index: https://base.platphormnews.com/sitemap-index.xml
- MCP endpoint: https://trace.platphormnews.com/api/mcp

## Core Trace Endpoints
- GET /api/v1/traces - public read - List meaningful public-safe actions from persisted storage.
- POST /api/v1/traces - protected - Ingest a trace and every validated observable span.
- GET /api/v1/traces/{traceId} - public read - Read one meaningful public-safe trace with redacted spans.
- GET /api/v1/traces/{traceId}/timeline - public read - Timeline view assembled from persisted spans.
- GET /api/v1/traces/{traceId}/tree - public read - Parent-child span tree view.
- GET /api/v1/traces/{traceId}/waterfall - public read - Waterfall view with span offsets and durations.
- GET /api/v1/traces/{traceId}/service-map - public read - Cross-service hop map for a public-safe trace.
- GET /api/v1/traces/{traceId}/critical-path - public read - Critical path view calculated from real span timing.
- GET /api/v1/traces/{traceId}/completion - public read - Trace completion state computed from real spans and expectations.
- POST /api/v1/traces/{traceId}/expectations - protected - Declare required, optional, or not-applicable spans before cross-site execution.
- POST /api/v1/traces/{traceId}/complete - protected - Recompute and persist trace completion.
- GET /api/v1/observatory - public read - Homepage truth model with source metadata and honest degraded states.
- GET /api/v1/observability/journeys - public read - Persisted per-system journey telemetry coverage without imposing one rigid span shape.
- POST /api/v1/spans - protected - Ingest every validated observable span and refresh trace aggregates.
- POST /api/v1/spans/start - protected - Start or attach a span to a trace.
- POST /api/v1/spans/annotate - protected - Append a redacted annotation event to a span.
- POST /api/v1/spans/complete - protected - Complete a span and recompute trace lifecycle.
- POST /api/v1/spans/fail - protected - Fail a span and recompute trace lifecycle.
- POST /api/v1/spans/cancel - protected - Cancel a span and recompute trace lifecycle.
- POST /api/v1/spans/heartbeat - protected - Record span heartbeat and pending state.
- POST /api/v1/async/traces - protected - Create a durable async trace envelope when storage is configured.
- POST /api/v1/async/jobs - protected - Create an async job linked to a trace.
- GET /api/v1/async/jobs/{jobId} - public read - Read public-safe async job status.
- GET /api/v1/jobs - public read - Alias for public-safe async job list.
- POST /api/v1/jobs - protected - Alias for protected async job creation.
- POST /api/v1/evidence - protected - Link redacted evidence to a trace or span.
- GET /api/v1/evidence - public read - List public-safe evidence records.
- GET /api/v1/search - public read - Search meaningful public-safe traces, spans, evidence, and playbooks.
- GET /api/v1/integrations/status - public read - Canonical graph, sitemap, catalog, and platphorm-* project integration coverage.
- GET /api/v1/projects - public read - All checked-out platphorm-* project integration records.
- GET /api/v1/projects/{project} - public read - One project mapping, evidence checks, and deterministic remediation guidance.
- GET /api/v1/playbooks - public read - Deterministic debugging playbooks.
- POST /api/v1/reports/trace-summary - public read - Generate a public-safe trace summary report from persisted evidence.
- GET /api/v1/aggregate/summary - public read - Trace lifecycle, ingestion, latency, service, and JA4 redaction aggregate summary.
- POST /api/v1/maintenance/trace-names - protected - Dry-run or repair bounded generic trace titles from persisted entry spans.
- POST /api/v1/otel/v1/traces - protected - Ingest OpenTelemetry trace payloads.
- GET /api/v1/network/graph - public read - Canonical graph/sitemap-derived network registry.
- GET /api/v1/network/trusted-domains - public read - Trusted-domain registry summary.
- GET /api/v1/network/route-compliance - public read - Route compliance state by site.
- POST /api/v1/network/route-compliance/run - protected - Run a bounded route compliance probe for one trusted domain.
- GET /api/v1/network/observability - public read - Observability compliance state by site.
- GET /api/v1/network/propagation - public read - Trace propagation state by site.
- POST /api/v1/network/graph/sync - protected - Refresh graph registry snapshots.
- POST /api/v1/sitemaps/sync - protected - Refresh sitemap coverage snapshots.
- GET /api/v1/sitemaps/coverage - public read - Graph and sitemap coverage summary.
- POST /api/v1/feeds/sync - protected - Refresh public feed snapshots.
- GET /api/v1/feeds - public read - Public-safe trace and incident feed summary.

## Trace Lifecycle
Trace status values: pending, active, waiting_for_spans, partially_complete, completed, failed, cancelled, timed_out, degraded, orphaned, unknown.
Span status values: pending, started, completed, failed, cancelled, timed_out, late, orphaned, degraded, unknown.
Async job status values: queued, claimed, running, waiting, completed, failed, cancelled, timed_out, degraded.
Completion is recomputed from real spans and expectations using trace-completion-v2.5.0; missing spans are never fabricated.

## Registered Workflows
- Public template: GET /api/v1/workflows
- Operator UI: /workflows/distributed-agent-publishing
- Protected 10-step story relay: POST /api/v1/workflows/story-format-relay-10/run
- Protected 15-step multimodal proof: POST /api/v1/workflows/multimodal-story-proof-15/run
- Protected launch: POST /api/v1/workflows/distributed-agent-publishing/run
- Protected no-mutation validation: POST /api/v1/workflows/distributed-agent-publishing/dry-run
- Plan: one root span, nine phase coordinators, ninety production, verification, or recovery operations, exactly 100 persisted trace steps.
- Outcome: a verified operator briefing, visual round trip, publication or recovery receipts, lineage manifest, readiness verdict, and proof bundle.
- Decision frames expose observation, decision, rationale, rejected alternative, confidence, and next action without exposing private chain-of-thought.
- The selector maps each option to its own registered endpoint and confirmation token; changing a label cannot launch a different workflow.

## Demonstrations
- Operator page: /workflows/distributed-agent-publishing
- Public-read suite: parallel Monitor and network-graph fan-out, intentional MCP failure and capability-discovery recovery, and an MCP host initialize/list/call exchange.
- Each persisted suite trace contains bounded web requests, internal Trace lifecycle requests, MCP arguments/results, response evidence, causal links, and a redacted final artifact.
- The 100-step briefing records operator-safe decision frames, requests, prompts, web and internal calls, published artifacts, and recovery receipts. Starting it is protected by PLATPHORM_API_KEY.
- The 10-step relay exercises live PlatPhormNews stories, Docs, Markdown, JSON, XML, OpenContent, PDF, ZIP, and Spec.
- The 15-step proof exercises BrowserOps, Evals, Sandbox, ASCII, deASCII, A2V, V2A, Docs, structured formats, OpenContent, Spec, and live stories.

## Span Persistence Policy
Authenticated trace envelopes and every validated observable span are stored when durable storage is available. Root spans, semantic operations, tool calls, timing, and parentage remain inspectable. The response reports spans_received, spans_ingested, spans_skipped, and span_persistence_reason.

## W3C Trace Context
Use traceparent and safe tracestate. Trace also understands X-PlatPhorm-Trace-Id, X-PlatPhorm-Span-Id, X-PlatPhorm-Parent-Span-Id, X-PlatPhorm-Request-Id, X-PlatPhorm-Source-Site, and X-PlatPhorm-Target-Site.

## x-vercel-ja4-digest
Trace may capture x-vercel-ja4-digest when present. Public display is hashed/redacted only. Raw values are not shown in public UI, RSS, sitemap, llms files, OpenAPI examples, client logs, or public traces.

## platphormctl Examples
- platphormctl trace start
- platphormctl trace headers
- platphormctl trace run -- <command>
- platphormctl trace inspect <traceId>
- platphormctl site inspect trace
- platphormctl mcp validate trace
- platphormctl policy inspect trace

## Discovery
- /api/docs
- /openapi.yaml
- /llms-full.txt
- /llms-index.json
- /.well-known/mcp.json
- /.well-known/agents.json
- /.well-known/trust.json

## Debugging Surfaces
- /playbooks
- /integrations
- /projects/{project}
- /api/v1/projects
- /clients/cli
- /clients/ide