Skip to main content
The artifacts pool holds files as tables. A table comes from a file that your Workspace published, or from a data file of a Parable. A published table sits next to Provider data. You can query it, join it from a Plot, or join it in an ad hoc query.
A table reaches this pool in one of three ways: 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.
To query this pool, you need the Data Access or Workspace Administrator role. Provider Policies do not apply to Artifact tables. The namespace of a Parable is different. Only SQL in that Parable reads it, whatever your role (Who reads a Parable’s tables).

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

  1. Upload the file.
  2. Review the schema. Parable saves an all-String schema at upload.
  3. Optional: infer column types, or replace the schema yourself.
  4. Publish the file with a table name.
  5. 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 PUT with every header in requiredHeaders, and the file as the body:
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.
3

Complete the upload

Parable checks the stored file, saves a sample, and saves an all-String schema. Read the file with GET /api/artifacts/{artifactId} until its uploadStatus is ready.

Upload limits

A file can be as large as the ARTIFACT_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:
The response is the publication work. Read the file with 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’s schemaInferenceStatus 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 as artifacts.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.
  1. Reserve. POST /api/artifact-publications/actions/reserve declares every table of the revision: its name, rowCount, sizeBytes, inputSha256, and inputFormat (CSV or ARROW_IPC_STREAM). Send expectedBaseRevisionId, the namespace’s active revision, or null for a new namespace. A table whose name, hash, and row count match the base revision reuses its stored data and gets no upload.
  2. Upload. The response has one entry in uploads for each table that needs data: an upload URL and the headers to send, as for a single file.
  3. Finalize. POST /api/artifact-publications/actions/finalize starts the analysis and the ingest of each table. Read the progress with POST /api/artifact-publications/receipt. Each table’s outputSchema appears there when Parable has derived it.
  4. Activate. When every table is ingested, call POST /api/artifact-publications/actions/activate. Parable switches the namespace to the new revision in one transaction.
Rules for a revision:
  • 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-String columns. 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. UInt32 becomes Int64. 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.
A namespace keeps its active revision, the revision before it, and every staged or failed revision until you remove it. To roll back, activate the previous revision and send the current active revision in 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 with 409 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 namespaceId and a new revision ID. The failed revision stays until you remove it.
  • Delete that namespace, then reserve with the new namespace ID.
When you do not have the error, send {"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:
For that request, each named namespace reads the selected revision. Other namespaces keep their active revision.
  • 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.
A malformed header fails with 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 (the parable.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.
Every Parable of a Workspace that has the Platform Parable loads these fonts, the way it loads its own: the frame asks for the families its CSS names, the shared stylesheet included. A Parable’s own font of the same family wins.

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:
Read the published schema from the catalog. Do not infer it from the source file. Query the pools has the Flight SQL clients for each language. A Report run reads an Artifact table at the last version published before the run’s AS OF time. A publication while the run waits is not part of that run.

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 setting ARTIFACT_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 is artifacts.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:
The Artifacts tree shows the table address of each data file, with Copy table address, and the state of the table: Building table, Table ready, or Table failed with the reason. A table that fails leaves the file as a file. The file still downloads, and Pane code still reads it. A data file that was checked before Parable files became tables gets its table the first time that someone lists the Parable’s files. When Parable staff rename the Parable’s handle, its SQL name changes too. That rename rewrites 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 a to z or 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.
So 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, and 1.
  • False: false, f, fa, fal, fals, no, n, of, off, and 0.
A Parquet column keeps the type that the file states, with three changes:
  • 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.
A JSON Lines field gets the type that its values share in the whole file: true or false, whole number, decimal number, text, or JSON.
  • 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 null are null. A blank line is not a row.
  • A line that holds no object, such as 42, fills one column, value.
Column names are the file’s header or field names, as written. Plot SQL quotes a name that has capitals or spaces, such as "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.
SQL outside the Parable fails with “artifacts.parable_perceptions holds the files of another Parable. Only SQL in that Parable reads it.” Ponder runs SQL in the Parable only when its SQL call names the Parable’s working copy or Release. Ponder SQL that names no Parable is Workspace SQL, so it cannot read the tables. It reads them through the Parable’s Plots.

A dataset that already holds the namespace

Before Parable files became tables, a Workspace could reserve a dataset whose namespace starts with parable_. 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.actors reads the dataset’s actors table 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.
Other Workspaces are not affected. A new dataset cannot take a 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.
A file that is over a bound, or that holds a line that is not JSON, gets a failed table. The tree shows the reason, such as “This file is too large to become a table.”

Files in Pane code

Pane code reaches the Parable’s files through the files 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 a Blob, 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 Workspace’s files reach Pane code only under three rules. The reader needs only a seat on the Parable.
  1. 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 with 403 and PA-AU-121: “This Pane does not declare that it reads the Workspace’s files.”
  2. 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.upload or admin.tenant.artifacts, the permissions of the Workspace’s own Artifacts list. Every save and every archive import checks this. Otherwise the save fails with PA-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.
  3. 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 403 and PA-AU-070.
The list leaves out every file that holds a Provider’s data: a file with an attributed connection, and a file that a tap reads, such as a published Artifact’s file. A download of such a file fails with 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 purpose ponder_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 errorMessage says “Save the file as UTF-8 and attach it again.”
  • WAV starts with RIFF, RF64 or BW64, then WAVE.
  • MP3 can start with zero bytes. Then it shows an ID3 tag, an APE tag (APETAGEX) or an MPEG frame sync.
A file that passes is 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 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:
The request must name a 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).
The media type that Parable stores, sends to the model and serves is the 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, be ready, 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 only data: 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.ts in apps/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 a tenant_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 whose url 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 own mimeType.
  • 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 size that the request names.
  • The first bytes match both the part’s mimeType and the contentType of the allowlist row, by the rules of the complete step. A browser that does not know the type can send application/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.

Errors