Skip to content

An artifact is attached to a message by fs.upload naming it in place of bytes: the session's server fetches the version's files from the plane as the person who asked, a pod over its control link for someone who steers the session and a daemon with its sign-in, so the bytes never pass through the client

Decision 990 · accepted · 2026-11-15 · issue #920 · supersedes 986

Issue #920's third part. The composer's "Add from artifacts" worked on this computer by the desktop reading each file through the daemon (artifact.read) and uploading it (fs.upload); on a pod the daemon is not in the path, so it was a void (Decision 986).

The server fetches; the client names. fs.upload takes {artifact, version?, file?, path?} in place of content: the artifact, the version (the one its address serves where none is named), one file of it, and the folder the files land in (session:/ where none is named), each at its own path in the artifact. The session's server asks the plane for the files through its host (Troupe.Artifacts.files/1, installed as the publisher is): a pod asks session.artifact.files over its control link, a daemon the plane's artifact.files with its sign-in. The bytes go plane to server; the client sends an id and receives where each landed. Not chosen: the client reading and uploading on the platform as it did here, which carries every byte twice through the person's connection and needs a sign-in on the client the pod does not need; and the plane writing into a pod's volume itself, which it has no path to.

As whom. The plane reads the artifact as the person on the connection, by the rules every read follows (Artifacts.visible/3: owner, team, audience, a link's holder). Over the control link the pod names that person, whom its session token's plane-signed subject says; the plane then also requires that they steer the session (owner, collaborator, or a team member with control), so a pod can fetch nothing for someone who has not joined one of its sessions. The control link's "no session content" rule (its module doc) is about what goes up; this goes down, the person's own choice into their session, as memory goes down with an activation. Audited as artifact.attach with the session, version and count.

Limits. 2 MB of files together in one attachment, under what one message of either path carries comfortably once in base64; past it the refusal says the size and to name one file. Every file is decoded and confined to the workspace before any is written, so a path that would leave it (forbidden) writes nothing. Binary files go as they are, unlike content, which is text: they never pass through JSON as text. Each written file is an fs_changed of the person's.

Refusals keep the plane's code. not_found for one the person may not see or a version or file that is not there; unavailable for a daemon not signed in ("troupe login signs it in"), a pod whose link is down, and a session under Local only, which asks the plane nothing.

The client. Both a daemon and a pod name fs_upload_artifact at initialize. The desktop then attaches the artifact itself (its title as the tag) and sends fs.upload with it as the message goes, saying in the message where each file landed, in /upload's words. On a platform session it lists the person's artifacts from the plane it is signed in to; on this computer from the daemon. Against a daemon from before it, the old path stands: each file read and uploaded. This replaces Decision 986's "Not yet on the platform".

What an older client sees. A capability it does not know; fs.upload with content as before.

Governs: apps/troupe_gateway/lib/troupe/gateway/artifacts.ex, apps/troupe_core/lib/troupe/artifacts.ex, apps/troupe_worker/lib/troupe/worker/artifacts.ex, apps/troupe_plane/lib/troupe/plane/artifacts.ex