artifacts.headcount is a short form of artifacts.public.headcount. The
short form never searches other namespaces. For a table in another namespace,
use the address that catalog discovery returns. Folders
only organize files in the app. They do not change a table’s SQL address.
Permissions
An operation that changes something, such as an upload or a publication, needs a Parable token. An MCP token can only list, read, preview, and browse files, and only while the Workspace allows external agents.
The Workspace Administrator role holds all of them.
Publish one file as a table
- Upload the file.
- Review the schema. Parable saves an all-
Stringschema at upload. - Optional: infer column types, or replace the schema yourself.
- Publish the file with a table name.
- Wait until the publication work succeeds. The table is queryable only after that.
Upload a file
An upload has three requests. The file’s bytes go straight to storage, not through the Workspace API.1
Reserve the upload
requestId is a new UUID. fileSize is the exact size in bytes.Response (shortened)
path places the file in a folder of the app. Send the same requestId
again to get the same reservation back, with a new URL.2
Send the file to the upload URL
Send a The URL works for 15 minutes. It accepts one file, of exactly the
reserved size, with those headers. It cannot replace a file. After it
expires, reserve the upload again.
PUT with every header in requiredHeaders, and the file as the
body:3
Complete the upload
String schema. Read the file with GET /api/artifacts/{artifactId}
until its uploadStatus is ready.Upload limits
A file can be as large as theARTIFACT_MAX_BYTES setting, which is 1 GiB by
default. The setting exists because of storage cost, and because the worker
reads the whole file to disk before it checks it. A Workspace upload accepts
.csv, .xlsx, .xls, .numbers, .ods, and .zip files. Only a CSV file
supports preview, schema inference, and publication. Other formats stay as
stored files.
Manage files and publish
Publish an uploaded file as
artifacts.public.headcount. ARTIFACT_ID is
the file’s ID. requestId is a new UUID for each new publication:
GET /api/artifacts/{artifactId} until data.publishWork.state is
SUCCEEDED. A FAILED state has an errorCode and an errorMessage. A
value that does not convert to the reviewed schema fails the publication.
Correct the schema or the file, then publish again.
If you send the same requestId with the same input again, you get the
existing work back.
Unpublish removes the table from SQL and keeps the stored file. Delete hides
the file and then removes its stored data. If a file is published, unpublish
it before you delete it.
The API Reference has the request and response of
each operation.
Schema inference and the model policy
Schema inference sends the CSV header row and up to five data rows to the model that the Workspace’s model policy chooses. It saves the column types that the model proposes. When the policy allows no AI processor for schema inference, Parable sends nothing. The call still succeeds. The file’sschemaInferenceStatus becomes
skipped_by_policy, and the file keeps its all-String schema. Replace that
schema yourself, then publish.
Publish a complete dataset
A publication puts several tables into one namespace of your own, such asartifacts.finance.*, and changes them together. Each version of the dataset
is a revision. Readers keep reading the active revision until every table
of a new revision is ingested and you activate it. A failed replacement
therefore leaves the previous dataset in place.
- Reserve.
POST /api/artifact-publications/actions/reservedeclares every table of the revision: itsname,rowCount,sizeBytes,inputSha256, andinputFormat(CSVorARROW_IPC_STREAM). SendexpectedBaseRevisionId, the namespace’s active revision, ornullfor a new namespace. A table whose name, hash, and row count match the base revision reuses its stored data and gets no upload. - Upload. The response has one entry in
uploadsfor each table that needs data: an upload URL and the headers to send, as for a single file. - Finalize.
POST /api/artifact-publications/actions/finalizestarts the analysis and the ingest of each table. Read the progress withPOST /api/artifact-publications/receipt. Each table’soutputSchemaappears there when Parable has derived it. - Activate. When every table is ingested, call
POST /api/artifact-publications/actions/activate. Parable switches the namespace to the new revision in one transaction.
- It holds 1 to 256 tables, each with a unique name, and each input from 1 byte to 1 GiB.
- A CSV table gets all-
Stringcolumns. Send an Arrow IPC stream for typed columns. Parable converts some Arrow types before it stores them: UTC and time-zone-free timestamps become microsecond timestamps, read as UTC.UInt32becomesInt64. Large and view strings become UTF-8. Other time zones, values that would overflow or lose sub-microsecond precision, and types that Parable cannot store fail the upload. - To retry unchanged inputs that failed, finalize again with
"retryFailed": true. A corrected input needs a new revision ID. - Activation fails when the active revision is no longer the base revision that you reserved against.
expectedActiveRevisionId.
A slug that another namespace holds
One live namespace holds a slug. A reserve that sends a new namespace ID with that slug fails with409 and WA-AF-031, and nothing is reserved. This
occurs when a publication failed and its rerun makes a new namespace ID. The
details of the error give namespaceId, the ID of the namespace that holds
the slug. Then do one of these:
- Reserve again with that
namespaceIdand a new revision ID. The failed revision stays until you remove it. - Delete that namespace, then reserve with the new namespace ID.
{"namespaceSlug": "finance"} to
POST /api/artifact-publications/namespaces/find. It returns the namespace
ID, the active and previous revision, and each revision that is not removed,
newest first, with its state and failure code. A slug that no live namespace
holds gives 404. This operation needs the permission to view Artifacts.
A producer that makes the same namespace ID from its Workspace and slug at each
run never gets this error.
Read a revision that is not active
A Flight SQL request can read another revision of a namespace, such as a staged revision that waits for review, or one revision pinned across several queries. Name it in the request metadata:- Name each namespace once, and at most 64 namespaces.
- The header grants nothing. You still need access to the artifacts pool.
- A revision that your Workspace does not list fails as not found.
- A prepared statement runs only under the selection that it was prepared with. To change the selection, prepare the statement again.
INVALID_ARGUMENT.
Parable files
A Parable has its own files, which people add at the top of its Piece tree. These files belong to one Parable in one Workspace. The Workspace’s Artifacts page does not list them. Another Parable and another Workspace cannot read them. A data file also becomes a table in the artifacts pool, and only SQL in its Parable reads that table (Data files become tables). Access follows the caller’s seat on the Parable: a seat that can view the Parable can read its files, and a seat that can edit it can add, rename, and delete them. A Pocketed Parable keeps its files read-only, as it keeps its Pieces. People and Ponder can read and download them, but every change (an upload, a rename, a family rename, a delete and a restore) gets the code a Piece save on a Pocketed Parable gets,PRIMARY_ARCHIVED, with “Restore it to change
them.” The rule reads both archives: the Workspace’s line and the
Parable. An upload and a restore hold both rows FOR SHARE in their
transaction, so a Pocket that comes after the seat check still stops them.
Ponder’s read callback says canEdit: false with the same sentence, so
Ponder draws no upload card that the person cannot answer.
A Parable accepts these formats. The allowlist is part of the platform
schema, so the API, the app, and the worker read the same list.
The worker checks each file before it is ready. The bytes must be the format
that the name declares. A PNG that is named
.jpg becomes a PNG, but an HTML
file that is named .png fails. An SVG must have no script, no event
attribute, and no outside address. A Pane can put an SVG’s markup into its
page, where the browser reads it as HTML, not XML. The two parsers end a
comment, a CDATA section, a declaration, a DOCTYPE and a name at different
characters. So the check also refuses a < or > in a comment, a
declaration or a DOCTYPE, a comment with -- or with a - at either end, a
< in a CDATA section or an attribute value, an element inside a title or
desc, and a name with a character that is not a letter, a digit, -, _,
. or :. The HTML parser also ignores xmlns, so an editor or metadata
element must have a prefix (inkscape:grid, rdf:RDF): without one, a p or
a style would become an HTML element. The worker reads the size of an image
or a video, the duration, frame size, and codec of a video (MP4, MOV, and WebM),
the names, weights, and axes of a font, the thumbnail of a Figma file, and the
columns, column types, and sample rows of a data file. In the check, a Parquet
column keeps its own type. A JSON Lines column takes the type that its sampled
values share, and the check stores a CSV column as text. The preview and
Ponder’s viewArtifact show a CSV column with the type that its sampled values
share, through one module (@parable/plots-data/artifact-columns), so a person
and Ponder read the same types. The table that a Parable’s data file becomes
reads the whole file, so its column types can differ from the sample’s
(Column types). When the table is ready, the preview and
viewArtifact show each column with the table’s type.
The worker counts the rows of a CSV file and reads the row count that a Parquet
file states. It gives a JSON Lines file no row count. Parable counts the rows
of a JSON Lines sample instead, when the sample holds the whole file. The
sample holds the whole file when the file has fewer than 500 rows, in at most
1 MiB. So the facts, the hover card, and the preview give the same number. A
larger JSON Lines file has no row count.
In the check, every decompressed read stops at ARTIFACT_DECODE_BUDGET_BYTES
(128 MiB by default), because the uploader writes the sizes in a file’s
headers.
A Parquet page decompresses whole, so the worker reads the page headers of the
first row group first. It adds the dictionary page and the largest data page
of each column that the first 500 rows need, and a file whose total is larger
than the budget fails with “This file is too large to check.” A GZIP or Brotli
page is decoded once to one byte past its declared size before the reader
holds it. The retired LZ4 codec is refused, because its reader ignores the
declared size. The sample decodes one row at a time, so a large value stops
the sample at its 1 MiB bound.
A Figma file’s thumbnail is a preview. The worker keeps it only when it is a
whole PNG whose IHDR gives 1 to ARTIFACT_THUMBNAIL_MAX_SIDE pixels a side
(4,096 by default) and whose size is at most ARTIFACT_THUMBNAIL_MAX_BYTES
(3,932,160 bytes by default, which is 5 MB of base64, the most that a model
reads in one image). It does not keep any other thumbnail, and the file still
passes with no thumbnail. The bounds exist because the header sizes come from
the uploader: Ponder sends the thumbnail to the model, and a browser that shows
it decodes every pixel.
A download is a signed URL that works for ARTIFACT_DOWNLOAD_URL_TTL (5
minutes by default). It names the file’s checked type and always downloads as
an attachment, so a browser never runs a file as a page. The UI offers Undo
for 5 minutes by default. This deadline does not remove bytes or end the
ability to restore an eligible file. A file is not versioned. Its bytes never
change, and a rename changes only its name.
When Parable staff delete a composed Parable, its files in every Workspace
leave discovery in the same transaction. Their bytes remain retained. A
Pocketed composed Parable keeps its files read-only. An upload or restore
that starts after the composed Parable is deleted gets “not found”.
An upload URL works for 15 minutes. While a file has not arrived, the list
gives uploadExpiresAt, the time its URL stops working. A file that is still
not sent ARTIFACT_UNFINISHED_UPLOAD_TTL (24 hours by default) after that time
is hidden while its staged bytes remain retained. The wait is long because an upload that
starts before the URL ends can continue on a slow connection.
A Pane shows a Parable file by its id with ArtifactImage and
ArtifactVideo, and a Palette names an uploaded font by its CSS name. A Pane
gets the bytes from the Parable page as a Blob. It never gets a storage
address. Pane code can also list and read the Parable’s files of every kind,
and add a file, with the files module (Files in Pane code).
The page adds no uploaded family whose name is the type that Parable gives
every frame, such as PP Fraktion Sans, and it sends the frame the list of those
names. Names compare as CSS compares them, without ASCII case, so a font whose
name table says pp fraktion sans cannot replace Parable’s type. The frame
reserves only the names on that list. A Palette’s own @font-face for an
uploaded family does not stop the uploaded faces from loading.
The frame first asks for the faces with no bytes (artifacts.fonts with
families: []). It then asks for the bytes of only the families that its CSS
names, in a style rule or a style attribute, and again each time its CSS
changes while an uploaded family is not added. A family that no Palette names
costs no signed URL and no download.
A file that is not available, and a file that the browser cannot decode, such
as a HEIC photo in Chrome, draw the fallback. The fallback sits in an element
with display: contents that carries data-artifact-missing (the id as the
Pane wrote it) and data-artifact-reason (unavailable or undecodable).
Ponder’s previewPane picture draws the same files. The capture page has no
session, so it asks ponder-api through the camera’s request route. ponder-api
lists the checked files of the turn’s Parable with the author’s seat
(listParableProblemMessageArtifacts), keeps the images, video, and fonts, and
serves the bytes of a kept file only. The same list stops
requestArtifactUpload from asking for files the Parable already has: when
files of the asked kinds are there, it draws no card and names them. A file whose base64 does not fit in one route answer (8 MiB)
draws its fallback. A Pane of another Parable draws its fallbacks. The camera
also reads the fallback marks in the Page frame, so a wrong id or a file name,
which never reaches the request route, is named in the picture’s summary under
drawnAsFallbacks, and a file the browser could not decode is named with the
formats to ask for instead.
Agents reach a Parable’s files through two operations:
view_parable_artifact and create_parable_artifact. Ponder’s viewArtifact
and createArtifact call them, and the hosted MCP endpoint serves them, so one
implementation serves both. Each applies the seat rule above, and each keeps
the @requirePermission of the Parable file operations. web-api reads and
writes the bytes itself, through the same signed URLs that a browser gets. A
signed URL stays in web-api: it is never in an answer, an error, or a log line.
view_parable_artifact answers the file’s details and what can be shown of it:
a picture as base64, an SVG’s markup, or a data file’s columns and sample rows.
The answer’s text and rows are fewer than 40,000 characters, and omitted says
what was left out. A picture is at most 3,932,160 bytes, which is 5 MiB of
base64, the most that a model reads in one image. A read in a Message stores
nothing, so its answer can pass the 4 MiB limit on a stored tool result. A Run
stores what it reads, so a Run’s answer holds no picture. One web-api pod reads
8 pictures at a time. Until the worker’s check ends, status is checking. It
never writes: data:read is its scope.
create_parable_artifact stores SVG, CSV, and JSON Lines text, the types that
the allowlist marks writableAsText. It reserves the upload with the same code
as a person’s upload, sends the bytes, queues the same check, and answers
checking. Its upload request ID comes from the idempotencyKey, the name, and
the text, so a repeated call finds its file and stores no second one. A call
that stopped before its check goes on from its reservation. In Ponder, web-api
makes the key from the Message and the arguments, and it keeps the
operation’s receipt, so a repeat in one Message is the same call. A new Message
stores a new file, with a number in its name when the name is taken.
When storage does not answer, web-api sends the bytes once more. If that also
fails, the call answers 503 and nothing is in Artifacts. An MCP host can repeat
the call with the same key, and it goes on from the reservation. In Ponder, the
receipt keeps that answer for the rest of the Message, and later edits still run,
so the person asks for the file again in a new Message.
An approved viewArtifact runs as viewArtifact, so the model sees the picture.
An approved createArtifact runs as the operation and answers checking.
createArtifact waits for the check only when the view runs without an approval.
The file carries madeByPonder, whichever agent made it. When the check refuses
such a file, the worker’s completion removes it in the same transaction, with
no undo. The person never sees a refusal written for an upload they did not
make, and the agent’s corrected file keeps the name. view_parable_artifact
still answers failed for its id, with the reason.
Fonts a Platform Parable’s Release brings
A Platform Parable can give every Parable a shared stylesheet (theparable.styles place, The shared stylesheet of a Platform Parable).
That stylesheet can name fonts that were uploaded to the Platform Parable in
the Workspace that makes it, by their CSS name, for example
--typography-font-family-sans: "Acme Sans", sans-serif.
Each Delivery of the Platform Parable’s Release copies those font files into
the Workspace it reaches:
- Only a Platform Parable’s files travel, only fonts, and only the fonts its stylesheet names. A font that the stylesheet stops naming is not copied again. Images, video, data files and every other upload stay in their Workspace.
- The copy is a file of the Workspace’s copy of the Platform Parable, and its bytes are in that Workspace’s own bucket. It has no uploader, because nobody in that Workspace uploaded it. The list shows “Uploaded by a Release”.
- A Workspace gets one copy of each font file. A later Release that names the same font copies nothing. A copy that failed is copied again by the next Delivery.
- The worker copies the exact bytes it checked in the Workspace that makes the Platform Parable, and checks the copy again as a font.
Decision record: how the fonts reach other Workspaces
Decided on 2026-10-27 for PARABLE-8478, before the code, because the fonts are data that leaves the Workspace that makes the Platform Parable.Join a published table
A published table joins other pools like any other table. This query joins a headcount plan to Provider directory data on a compatible email column:Files in a composed Parable
A composed Parable keeps its files in one Workspace. A different composed Parable or Workspace cannot read those files, except the fonts that a Platform Parable’s shared stylesheet names (Fonts a Platform Parable’s Release brings). The Workspace’s Artifacts page does not list them. A data file’s table is in the artifacts pool, in the namespace of the Parable, and only SQL in that Parable reads it. Each composed Parable can retain 1,000 files by default. Unfinished and soft-deleted files count because their bytes remain stored. The platform settingARTIFACT_MAX_FILES_PER_PARABLE controls this bound. A new upload
that would exceed it is refused. A retry keeps its existing reservation.
Restore uses no new place because the file is already retained.
Files are shared by every Release and Problem of the composed Parable in
this Workspace. An upload, rename, font copy, deletion, or restore takes effect
immediately. These changes do not enter a Patch and do not wait for publication,
including in Published Versions mode. Choosing an older Release does not
restore an earlier file set.
Anyone with Primary, Publishing, Pinging, or Peeking who can open the composed
Parable can list and download every file. This includes a file that no released
Pane uses. Pane Policies do not narrow access to these files. A person with
Primary or Publishing can change them. A Pocketed composed Parable keeps its
files read-only, and so does a Workspace’s copy of a Platform Parable: its
files come from the Platform Parable’s Releases, as its Pieces do, and a
change is refused with PA-AU-067. A Release or Deployment to another
Workspace carries no files, except the fonts a Platform Parable’s shared
stylesheet names.
Deleting a file hides it from Artifacts. It retains the file and its checked
bytes indefinitely. Existing Page, Pane, image, video, and font references
continue to work, including after a reload and after the Undo offer ends.
No composed Parable file is physically removed for now. The short Undo offer
returns a file to discovery. An eligible retained file can also be restored
later. Optional file versioning in Published Versions is a separate follow-up.
Data files become tables
A CSV, Parquet, JSON Lines, or gzipped JSON Lines file of a composed Parable becomes a table after its check. It needs no publish step. The table’s address isartifacts.parable_<the Parable's SQL name>.<table>. The Parable’s
SQL name is the one in its Plot addresses, parables.<parable>.<plot>.
For example, a file actors.csv in the Parable whose SQL name is
perceptions becomes artifacts.parable_perceptions.actors. Its header and
its values gave these columns:
artifacts.parable_<old> to artifacts.parable_<new> in the
Parable’s own SQL, as it rewrites parables.<old>. An archive import from a
Parable with another SQL name gets the same rewrite, to the SQL name of the
Parable that it goes into.
Table names
The table name is the file name without its extension, by the rule for SQL names:- Letters lose their accents and become lower case.
- Each run of characters that are not a letter from
atozor a digit becomes one_. No_stays at either end. - A name that starts with a digit gets
p_in front. - A name with nothing left is
file.
Actors 2026.csv becomes actors_2026, and 2026 plan.csv becomes
p_2026_plan. When a live file of the Parable already holds the name, the new
table gets _2, _3, and so on. Of actors.csv and actors.parquet, the
first file to become a table keeps actors, and the other gets actors_2.
The name stays with the file:
- A rename changes only the file’s name. The table keeps its address, so the Plots that read it keep working.
- A delete removes the table from SQL at once and frees its name.
- A restore, or Undo after a delete, brings the table back under its name when the name is free. Otherwise the table gets the next free number.
- To replace a file’s data, delete the file and upload the new file under the same name. The new file takes the freed table name, so the Plots keep their SQL and read the new rows.
Column types
The worker reads the whole file to choose the type of each column. It calls no model, so the Workspace’s model policy does not apply. In a CSV file, each column gets the first type in this list that every non-empty value fits. An empty cell is null, and a column with no values is text.
Because whole numbers come first, a column of only
0 and 1 is a whole
number. A column whose date and time values are all at midnight is a date.
A value with a leading zero before another digit, such as 02134, -0123, or
+0123, is not a number, so a column that holds one takes the next type that
fits, usually text. A ZIP code keeps its zero. 0, 0.5, -0.5, and 10
stay numbers.
True or false takes these values:
- True:
true,t,tr,tru,yes,y,ye,on, and1. - False:
false,f,fa,fal,fals,no,n,of,off, and0.
- A nested column, such as a list or a struct, is JSON text.
- A decimal column is text. Cast it in SQL, as in
CAST(price AS DOUBLE). - A timestamp with a time zone keeps its instant, as UTC.
- Whole numbers and decimal numbers together are decimal numbers. Any other mix of types is text.
- An object or an array is JSON.
- A whole number too large for a 64-bit integer makes its field a decimal number.
- A date in a JSON string stays text. Cast it in SQL.
- A missing field and a JSON
nullare null. A blank line is not a row. - A line that holds no object, such as
42, fills one column,value.
"Full Name". In a CSV file,
Parable removes the spaces at either end of a header. An empty header becomes
col_ and its position, such as col_3. A repeated header gets _2, _3,
and so on. A Parquet file whose two columns share a name gets a failed table.
Who reads a Parable’s tables
Only SQL that runs in the Parable reads its tables:- The Parable’s Plots read them for every person who can open the Parable, Peeking included.
- Other SQL in the Parable, such as the Plot editor’s Preview, a Lab’s
query(), or Ponder’s SQL in the Parable, reads them only for a person who can edit the Parable’s Plots. That person holds Primary or Publishing on the Parable and the Build Parables permission (tenant.parables.manage). A person with Pinging or Peeking reads the tables through Plots. - SQL in another Parable, and Workspace SQL outside every Parable, cannot read them, whatever the role. Catalog listings outside the Parable do not show them.
A dataset that already holds the namespace
Before Parable files became tables, a Workspace could reserve a dataset whose namespace starts withparable_. That dataset keeps its namespace and takes
new revisions. When the namespace is the one of a Parable in that Workspace,
such as parable_perceptions, the dataset wins in that Workspace:
- SQL reads the dataset at
artifacts.parable_perceptions, with the same roles as any other dataset. The rule that only SQL in the Parable reads the namespace does not apply. - The Parable’s file tables are not served in that Workspace. A Plot that reads
artifacts.parable_perceptions.actorsreads the dataset’sactorstable when the dataset has one. Otherwise the Plot fails as for any missing table, or reads an empty table when it declares the table as an optional Artifact input. - The Artifacts tree still shows each data file’s table address and state, such as Table ready. Nothing in the tree says that the dataset holds the namespace. Query Layer logs a warning that names the namespace and the Parable.
parable_
namespace.
Two Parables with the same SQL name
Some Parables made before SQL names were unique share one. When two of them have a line in one Workspace, both claim the same namespace. No SQL in that Workspace reads it, in either Parable or outside both, so neither Parable reads the other’s files. Query Layer logs a warning that names the namespace.A Workspace with no file
A Release or a Deploy carries no files, so a copy of the Parable in another Workspace starts with none. A Plot that reads a missing Parable table fails, as for any missing table. To read an empty table with the declared columns instead, declare the table as an optional Artifact input of the Plot (Optional Artifact inputs). Declare every Parable table that a Plot reads.Bounds
A table adds these bounds to the bounds of a Parable file:- A gzipped JSON Lines file decompresses to at most 1 GiB.
- One JSON line is at most 1 MiB.
- A JSON Lines table holds at most 2,000,000,000 cells: its rows times its columns. Every row holds every column, so a file of many short lines that together name many fields can pass this bound while it is small.
- The pages of one Parquet row group decompress to at most
ARTIFACT_DECODE_BUDGET_BYTES, 128 MiB by default.
Files in Pane code
Pane code reaches the Parable’s files through thefiles module of the Pane
SDK. A Lab imports the same files from parable
(Read data from the app).
files.list()lists the Parable’s files of every kind. A data file carries its table address and the table’s state.files.list({ from: 'workspace' })lists the Workspace’s checked files.files.read(id)returns one file as aBlob, at most 25 MB. Read the rows of a larger data file through a Plot.files.upload()works only after a click or a key press in the Page. The host opens its own file picker, and the file goes into the Parable’s files. Only a person with Primary or Publishing adds a file, and only in the Publishing mode.
- The Pane or Page whose code asks declares
readonly workspaceFiles: true;in its Perception, in the Pieces that the frame runs. Otherwise the call fails with403andPA-AU-121: “This Pane does not declare that it reads the Workspace’s files.” - Only a person who holds a permission that lists the Workspace’s files by
their own grants saves a Perception that declares it:
tenant.artifacts.view,tenant.artifacts.uploadoradmin.tenant.artifacts, the permissions of the Workspace’s own Artifacts list. Every save and every archive import checks this. Otherwise the save fails withPA-AU-120: “Only a person who can view the Workspace’s files can let a Pane read them.” A copy that takes a Release by Pull or by Delivery is not a person’s save, so this rule does not apply to it. - Everyone who last saved the code in the frame holds one of the same
permissions: the code of every Page and Pane of the Parable, plus any shared module in its build, which the
frame can run. Otherwise the call fails with
403andPA-AU-070.
404. Each listed file
carries its id, name, type, kind and size, and no uploader.
The server cannot tell which code asks. Through a Pane that declares
workspaceFiles, a reader can list and read every other checked Workspace
file, not only the files that the Pane shows.
Panes
documents each call and its refusals.
Files attached to a Ponder Message
A file that a person attaches to a Ponder Message is a Ponder chat attachment (PARABLE-9732). Its bytes go straight to the Workspace bucket through a signed URL, as an Artifact upload does. The upload never passes through the Workspace API. The Workspace API reads the bytes again only to send them to the model (see How the model reads an attachment). Parable keeps the attachment in the same table as an Artifact, with the purposeponder_attachment. It is not an Artifact: no Artifact list,
Artifact read, Parable file list, count or cleanup shows it, and it never
becomes a table.
Attach a file
1
Reserve the attachment
POST /api/ponder/attachments/actions/prepare with a new requestId, the
fileName, the exact fileSize in bytes, and the mediaType that the
browser reports. The answer holds attachmentId, uploadUrl,
requiredHeaders and expiresAt. Send the same requestId again to get
the same reservation back, with a new URL.2
Send the file to the upload URL
Send a
PUT with every header in requiredHeaders and the file as the
body. Send no Parable credentials to this URL. It works for 15 minutes,
for one file of exactly the reserved size, and it cannot replace a file.3
Complete the attachment
POST /api/ponder/attachments/actions/complete with the attachmentId.
Parable reads the size of the stored file and its first 512 bytes. The
file must exist, have exactly the reserved size, and start with the bytes
of the type that its name declares:- An image or a PDF shows its own signature.
- Text, Markdown, CSV and JSON have no NUL byte and do not start with a
known binary signature, such as ELF, ZIP or PNG. The text need not be
UTF-8, so a CSV that a spreadsheet saved in Windows-1252 passes. UTF-16
text fails, and
errorMessagesays “Save the file as UTF-8 and attach it again.” - WAV starts with
RIFF,RF64orBW64, thenWAVE. - MP3 can start with zero bytes. Then it shows an ID3 tag, an APE tag
(
APETAGEX) or an MPEG frame sync.
ready. A file
that fails is failed, and errorMessage says why. A repeat on a ready
attachment answers ready again. Only the person who reserved the
attachment can complete it.4
Send the Message
A file part of the Message names the attachment with the URL
The request must name a
parable-attachment:<attachmentId>, such as
{ "type": "file", "mediaType": "image/png", "filename": "chart.png", "url": "parable-attachment:4fQ9zR2mKx8TvB1nC7pLd" }.
The chat route and appendParableProblemMessage, which the MCP tools
send_problem_message and ask_ponder_to_work call, both accept it.
In appendParableProblemMessage, the part is an attachment part:mimeType, a size and a filename, but the
server replaces all three with the attachment’s stored type, size and
name.The url of an attachment part is a parable-attachment: reference or
a base64 data: URL, and nothing else. The server refuses any other URL,
such as an https: address, with 400 and WA-AF-030, and nothing is
written (Inline files).contentType of the file’s row in the allowlist. Parable never uses the
media type that the browser reports.
What an attachment may be
The allowlist is
artifact-file-type-table.platform-default.json in
platform-schemas/services/connectors-shared-types/src/defaults. Its
refusal rows give the words that a refused file shows. The web app reads the
same table for its file picker and for its refusals, before it reserves a
file.
The Message limits are MaxCount and MaxTotalBytes in
services/web-api/internal/ponderattachments/ref.go. The web app holds the
same two values once, as PONDER_ATTACHMENTS_MAX and
PONDER_ATTACHMENTS_BYTES_MAX in
apps/web-app/app/domains/parables/pane-runtime/bridge/bridge-protocol.ts. The composer,
a Ping answer and a Pane’s ponder.ask all refuse files past them before
the send (PARABLE-9795). A Ping card sends the answers to all of its
questions in one Message, so the files of every question count together.
Who may send an attachment
The send checks each attachment in the transaction that writes the Message, with the attachment row locked. The attachment must be in the Workspace, beready, and have the sender as its uploader. The first Message that sends it
binds it to that Message’s Problem. After that, only Messages of that Problem
can send it. A refused attachment refuses the whole Message with 400 and
WA-AF-029, and nothing is written.
The stored Message part and the stored UI message keep the reference, not the
bytes. A retry of the Message and a Retry of a reply send the same reference
again.
How the model reads an attachment
ponder-api reads onlydata: URLs. When web-api sends a Message to ponder-api,
and when it seals the prompt of a Run, it reads the bytes of each attachment
and replaces the reference with a data: URL. At each read it checks again
that the attachment is a ready attachment of this Problem. A reference that
fails the check, or whose stored file is missing or changed, becomes a text
part that names the file. So a reference that someone copies into another
Problem’s Message never sends that file to the model. The reads of one
Message stop at 20 MiB. The prompt of a Run also inlines at most 20 MiB in
total: the newest Messages come first, and each attachment that does not fit
in what is left becomes the text part. A smaller attachment after it can
still fit. web-api reads at most 4 objects at a time.
ponder-api reads text only as UTF-8. When a text, Markdown, CSV or JSON
attachment is not valid UTF-8, web-api reads it as Windows-1252 and sends it
as UTF-8. Windows-1252 holds every printable Latin-1 character.
A read error that a later read can fix fails the reply, or the start of the
Run, and nothing is sealed with a placeholder for good. These errors are a
storage answer 5xx or 429, a timeout, and a cancelled or expired request.
A Run that fails so has the code PONDER_RUN_ATTACHMENT_UNREADABLE and the
message “An attached file could not be read, so Ponder did not start this
Run. Start a new Run to try again.” Nothing starts that Run again, because
the reconciler restarts only pending Runs. The error is retryable: Retry
sends the Message again with the same attachments, and the new Run reads
them again.
Every other read error makes the text part. A warning names the Workspace,
the attachment and the error, and the counter
parable.ponder.attachment.read_misses counts it with a cause:
pi’s session journal of a Problem keeps a picture under its own scheme,
parable-image:<sha256>. That scheme names a copy of the picture’s bytes in
the journal’s store, and parable-attachment: names an attachment row that
web-api checks at every read, so the two schemes stay separate.
Open an attachment
GET /api/parable/problems/{problemId}/attachments/{attachmentId}/content
answers 302 to a signed download that works for 5 minutes. The download
has the stored media type and the file name. The reader must be able to read
the Problem, by the rule that getParableProblem uses, and the attachment
must be a ready attachment of that Problem. Otherwise the answer is 404.
The browser follows the redirect and reads the bytes from storage. The web
app proxy hands the redirect to the browser instead of following it, so no
attachment bytes pass through a web-app pod. An audio or video player that
plays after the 5 minutes asks the route again when its address stops
working.
An image that a person sends shows at once, and never as a broken image
(PARABLE-11764). The route answers 404 until the Message that binds the
attachment to its Problem is written, so the thread does not show the route’s
answer until the image has loaded:
- Before the send, the composer gives the thread the object URL of each image
that the person picked (
ponder-sent-previews.tsinapps/web-app/app/domains/parables/components/ponder-chat). The copy of the Message that is not written yet shows that local copy, or a Skeleton when there is none, and it does not ask the route. - The written Message loads the stored file in a hidden element. Until the load event, the thumbnail shows the local copy, or a Skeleton of its size when the tab has no local copy, such as after a reload. Then the thumbnail shows the stored file, and the web app revokes the object URL.
- A load that fails tries again after 1 second and after 3 seconds. Then the thumbnail shows “Image did not load” with Retry, and the web app revokes the object URL.
- A send that fails gives the copies back to the composer, which keeps the files.
Protected Workspaces
A Workspace that uses customer-supplied storage keys has atenant_storage_encryption row. Prepare refuses it with 409 and
WA-AF-027, because web-api cannot read that bucket for the model. In such a
Workspace, the file goes inline in the Message as a base64 data: URL, as
every attachment did before. The request body of the chat route is at most
32 MB.
Inline files
An inline file is an attachment part whoseurl is a base64 data: URL. The
chat route, appendParableProblemMessage (send_problem_message) and
startParableProblemRun (ask_ponder_to_work) run one check on it:
CheckInline in services/web-api/internal/ponderattachments/check.go
(PARABLE-9793).
- The URL is
data:<mimeType>;base64,<bytes>, with the part’s ownmimeType. - The file name ends with an extension of the allowlist, as for an upload.
- The file holds 1 byte to 5 MiB. The stored size is the size of the decoded
bytes, not the
sizethat the request names. - The first bytes match both the part’s
mimeTypeand thecontentTypeof the allowlist row, by the rules of the complete step. A browser that does not know the type can sendapplication/octet-stream. - Inline files and references together are at most 10 files and 20 MiB in one Message.
appendParableProblemMessage and startParableProblemRun refuse an inline
file with 400 and the WA-AF code in the table below. The chat route uses
its own codes. It answers 413 with PA-CH-007 when an inline file or the
inline files together are too large. It answers 400 with PA-CH-013 for
every other refusal of an inline file.
A Message stored before PARABLE-9793 can hold an attachment part with an
external URL. The web app shows such a part as its file name only. It never
puts a URL that is not a data: URL in <img src>, so a reader’s browser
requests nothing from that address.
Retention
An attachment that no Message sent goes 24 hours after it was created, whatever its upload status. web-api’s hourly maintenance step deletes the row (expiredRowTables in services/pkg/parable/maintenance_expired.go).
No route deletes a Problem. The rows of a sent attachment go when the hard
delete of a Parable’s Deployment cascades to its Problems, and from them to
the attachments. In both cases the stored file stays in the bucket until
PARABLE-9792 removes it.