ArtifactRead the labels first
Current behavior and future direction are not mixed.
- Current invariantBehavior enforced by the application today.
- Product guidanceA choice ArtifactFlow recommends to people and agents, but cannot infer from content alone.
- Roadmap directionA design constraint for future format work, not an alpha feature claim.
Current invariant
The managed record stays stable while content moves forward.
A page is the managed artifact. It has a stable artifact UID that remains the same while its content changes. Every stored content revision receives its own version UID and version number, and the artifact points to the current version.
Creation stores immutable version one. A content update appends another immutable version and advances the current pointer. Retained versions remain in history, while links, access, ownership, hierarchy, taxonomy, and audit attach to the stable artifact. When the configured per-artifact limit is exceeded, ArtifactFlow prunes the oldest whole versions and records that pruning.
Current invariant
Who submitted a version and who produced its content are different facts.
Every version has an ArtifactFlow-observed ingest record: actor, mechanism, retained-byte hash, and timestamp, plus unverified MCP-reported client metadata when applicable. A version may also carry declared AI, human, or software producer assertions. AI declarations identify the provider and exact model ID, but remain self-reported unless a future provider attestation proves more.
Restoring content creates a new version and records where the bytes came from, so the restoring user or client is not mislabeled as the content producer. Provenance survives ordinary version-content pruning, remains protected by the page's permissions, and can be searched by provider/model across page origin, current version, or any historical version.
An MCP client name such as Claude Code is caller-reported metadata that proves neither the submitting implementation nor the model that authored the content. If the caller does not know the model, ArtifactFlow preserves that uncertainty.
Product guidance
Keep the identity when the artifact still does the same job.
Append a version when the purpose, durable link, expected audience, ownership, and access remain conceptually continuous. A complete rewrite can still be a new version of the same calculator or runbook.
Create a new artifact when both results should coexist, the work has forked into another purpose, audience, owner, or access boundary, or carrying the old identity forward would make its links and history misleading.
ArtifactFlow cannot determine semantic identity by counting changed bytes. The person or agent performing the write chooses whether the result continues an existing artifact or begins an independent lifecycle.
Current invariant
Draft is a lifecycle status, not mutable content.
A newly created artifact starts in Draft with an immutable first version. Every saved content update appends an immutable version, including while it remains in Draft. Editing Approved or Deprecated content returns the artifact to Draft because the revised content has not retained the previous status.
A status transition does not itself create a content version. An unsaved single-file HTML draft preview is different again: it renders temporary editor input on the isolated artifact origin, creates no version, and does not alter the stored artifact.
- Draft statusSaved lifecycle state backed by immutable content versions.
- Unsaved draft previewEphemeral editor content that has not been persisted.
Current invariant
Content history and catalog changes use different concurrency paths.
A content version retains the authoritative payload. Catalog metadata such as title, description, category, parent, owner, and tags belongs to the stable artifact record.
Metadata writes use a separate optimistic metadata revision and produce domain events and audit entries. A metadata revision is not a content-version snapshot, and content history does not currently promise to restore historical catalog metadata.
Current formats
Source, result, and preview depend on the payload type.
Single-file HTML
The retained payload is both source and executable result. It runs on the separate artifact origin under the documented iframe, CSP, signed-capability, and no-app-cookie boundary.
Markdown and Mermaid
The retained payload is Markdown source. The application derives its rendered view, and untrusted raw HTML or JavaScript never executes in the authenticated application DOM.
Roadmap direction
Document formats keep the original and derive bounded ways to use it.
PDF and DOCX support is roadmap work, not current behavior. Each replacement is intended to append an immutable version with a private original. Bounded, isolated processing may derive searchable text, OCR output, structural metadata, and a safe non-executable preview.
The planned boundary keeps authorization consistent across search, preview, download, version history, MCP, processing status, and deletion. Per-version catalog metadata is not promised; that needs a separate product and data-model decision.
For generated DOCX, preserving an optional generator source such as Markdown or Python beside the binary original remains an open design question. ArtifactFlow must not pretend every uploaded document has one.