@kernhq/module-quire 0.13.0 → 0.14.0

package/src/client/transfers.ts

@@ -0,0 +1,142 @@
+import type { ExportFormat, ExportScope, ImportSource, TransferState } from '../contract/index.js'
+import { t } from './i18n.js'
+
+/**
+ * The bits of the transfer screens that are not a screen.
+ *
+ * Two dialogs and a page draw the same four vocabularies — a scope, a format, a source and a state
+ * — and the same download. Written out once here because the alternative is four copies of a
+ * `switch` that has to agree with the contract's enums: a `TransferState` gaining a fifth member
+ * would then be four silent gaps rather than one type error.
+ *
+ * Every label is a function rather than a constant. A module is defined once at import time while
+ * the interface language can change afterwards, so a map built at module scope would be frozen in
+ * whatever language happened to be loaded first — the same reason `module.ts` writes its nav labels
+ * as getters.
+ */
+
+/** The four states, as a person reads them rather than as the column stores them. */
+export function stateLabel(state: TransferState): string {
+  return state === 'queued'
+    ? t('transfer_queued')
+    : state === 'running'
+      ? t('transfer_running')
+      : state === 'done'
+        ? t('transfer_done')
+        : t('transfer_failed')
+}
+
+/**
+ * What a state looks like at a glance.
+ *
+ * `queued` and `running` share the spinner deliberately: the difference between "a worker has not
+ * picked this up" and "a worker is on it" is the sentence beside the icon, not the icon — two
+ * different in-progress glyphs would be two things to learn for one meaning.
+ */
+export function stateIcon(state: TransferState): string {
+  return state === 'done' ? 'circle-check' : state === 'failed' ? 'triangle-alert' : 'loader'
+}
+
+/** Where the export took its pages from. */
+export function scopeLabel(scope: ExportScope): string {
+  return scope === 'page'
+    ? t('export_scope_page')
+    : scope === 'subtree'
+      ? t('export_scope_subtree')
+      : t('export_scope_space')
+}
+
+/**
+ * The formats a person may actually pick.
+ *
+ * `docx` is in `ExportFormat` and is not here, because the server refuses it at `exports.start` —
+ * see `services/export.ts` for why a Word file nothing in this repository can open is worse than a
+ * refusal. Offering a control whose only outcome is an error is the shape this list exists to
+ * prevent; the dialog says the same thing in a sentence instead, which answers the question
+ * ("where is Word?") without pretending to have an answer it does not have.
+ */
+export const EXPORT_FORMATS: readonly Exclude<ExportFormat, 'docx'>[] = ['markdown', 'html', 'pdf']
+
+export function formatLabel(format: ExportFormat): string {
+  return format === 'markdown'
+    ? t('export_format_markdown')
+    : format === 'html'
+      ? t('export_format_html')
+      : format === 'pdf'
+        ? t('export_format_pdf')
+        : t('export_format_docx')
+}
+
+export function formatDescription(format: Exclude<ExportFormat, 'docx'>): string {
+  return format === 'markdown'
+    ? t('export_format_markdown_desc')
+    : format === 'html'
+      ? t('export_format_html_desc')
+      : t('export_format_pdf_desc')
+}
+
+export const IMPORT_SOURCES: readonly ImportSource[] = ['notion', 'confluence', 'markdown']
+
+export function sourceLabel(source: ImportSource): string {
+  return source === 'notion'
+    ? t('import_source_notion')
+    : source === 'confluence'
+      ? t('import_source_confluence')
+      : t('import_source_markdown')
+}
+
+export function sourceDescription(source: ImportSource): string {
+  return source === 'notion'
+    ? t('import_source_notion_desc')
+    : source === 'confluence'
+      ? t('import_source_confluence_desc')
+      : t('import_source_markdown_desc')
+}
+
+/** Neither `done` nor `failed`, so something is still going to happen to it. */
+export const isRunning = (state: TransferState): boolean => state === 'queued' || state === 'running'
+
+/**
+ * How far along a job is, as a fraction, or `null` while there is nothing honest to draw.
+ *
+ * `total` is 0 until the job has finished counting what it is about to do, and a bar sitting at 0%
+ * for the first few seconds of every export reads as a job that is stuck. Null means "say it is
+ * running, in words" — which is true — rather than drawing a measurement nobody has taken.
+ */
+export function progressRatio(counts: {
+  total: number
+  done: number
+  skipped: number
+  failed: number
+}): number | null {
+  if (counts.total <= 0) return null
+  const seen = counts.done + counts.skipped + counts.failed
+  return Math.max(0, Math.min(1, seen / counts.total))
+}
+
+/**
+ * Fetch an artefact the browser has just been given a link to.
+ *
+ * A hidden anchor rather than `location.href`, and rather than `window.open`: `open` is what a
+ * pop-up blocker stops when it happens after an `await`, and assigning `location` sends the whole
+ * document at a URL that only *usually* comes back as a download. A click on an `<a>` is the one
+ * gesture every browser treats as "fetch this file", and the page it happened on is untouched.
+ *
+ * `filename` is honoured for a same-origin address only — the `download` attribute is ignored
+ * cross-origin, which is every real instance, where the name comes from the `Content-Disposition`
+ * the presigned URL was signed with. It is passed anyway because `dev:mock` hands back a `data:`
+ * URL, and there the attribute is the only thing that names the file.
+ */
+export function startDownload(url: string, filename?: string): void {
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.rel = 'noreferrer noopener'
+  if (filename) anchor.download = filename
+  anchor.style.display = 'none'
+  document.body.appendChild(anchor)
+  anchor.click()
+  anchor.remove()
+}
+
+/** An error as a line of text, whatever was thrown. */
+export const messageOf = (err: unknown): string => (err instanceof Error ? err.message : String(err))

package/src/contract/models.ts

@@ -321,4 +321,156 @@ export const Publication = z.object({
 })
 export type Publication = z.infer<typeof Publication>
 
+// =====================================================================================
+// Getting work in and out
+// =====================================================================================
+
+/**
+ * How much of the tree an export takes.
+ *
+ * `page` is one page; `subtree` is a page and everything under it; `space` is every page in a space.
+ * The three are not a convenience — they are the three questions people actually ask ("send me this",
+ * "send me this section", "get us off this product"), and the middle one is the one a flat
+ * page-by-page export cannot answer without somebody clicking three hundred times.
+ */
+export const ExportScope = z.enum(['page', 'subtree', 'space'])
+export type ExportScope = z.infer<typeof ExportScope>
+
+/**
+ * What comes out.
+ *
+ * `html` and `pdf` are rendered by the same static renderer the public site uses — never the live
+ * document and never the draft, so an export of a `page` is what a reader is served rather than what
+ * the last person to open it happened to be typing.
+ */
+export const ExportFormat = z.enum(['markdown', 'html', 'docx', 'pdf'])
+export type ExportFormat = z.infer<typeof ExportFormat>
+
+/** Where a transfer is. `done` and `failed` are terminal; nothing moves out of either. */
+export const TransferState = z.enum(['queued', 'running', 'done', 'failed'])
+export type TransferState = z.infer<typeof TransferState>
+
+/**
+ * A job's own progress, shared by both directions.
+ *
+ * `skipped` is the counter that matters and the one a progress bar leaves out. An export skips a page
+ * the requester may not read; an import skips a file it cannot map. Reporting the count is the
+ * difference between an artefact that is quietly missing things and one that says how many.
+ *
+ * Every field defaults, so a job that has not started yet parses as four zeroes rather than as
+ * absent — a client should never have to distinguish "no progress" from "no counters".
+ */
+export const TransferCounts = z.object({
+  total: z.number().int().nonnegative().default(0),
+  done: z.number().int().nonnegative().default(0),
+  skipped: z.number().int().nonnegative().default(0),
+  failed: z.number().int().nonnegative().default(0),
+})
+export type TransferCounts = z.infer<typeof TransferCounts>
+
+/**
+ * A request to take a page, a subtree or a space out of Quire as a file.
+ *
+ * There is no artefact URL here and there should not be. `fileId` is an opaque id, not an address:
+ * the download is a signed URL a procedure mints per request, so that the fence on who may fetch a
+ * subtree export — which flattens pages of different readerships into one file — is applied at the
+ * moment of the fetch rather than baked into a link that outlives it. A client that builds a storage
+ * key from an id is the mistake `migrations/0009` had to go back and scrub out of published HTML.
+ */
+export const ExportJob = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  requestedBy: UserId,
+  scope: ExportScope,
+  /** the page for `page` and `subtree`, the space for `space`; `scope` says which */
+  targetId: Id,
+  format: ExportFormat,
+  state: TransferState,
+  /** null until the job succeeds — an artefact that is still being written is not offered */
+  fileId: Id.nullable(),
+  /**
+   * Why it failed, in the words of whatever failed — a Gotenberg refusal, the name of a page that
+   * would not render. Diagnostic, not a user-facing string: a screen says its piece from a message
+   * key chosen by `state`, and shows this beside it for the person who has to act on it.
+   */
+  error: z.string().nullable(),
+  counts: TransferCounts,
+  createdAt: Timestamp,
+  /** null while `queued` or `running` */
+  finishedAt: Timestamp.nullable(),
+})
+export type ExportJob = z.infer<typeof ExportJob>
+
+/** What kind of export is being read in. */
+export const ImportSource = z.enum(['notion', 'confluence', 'markdown'])
+export type ImportSource = z.infer<typeof ImportSource>
+
+/**
+ * What happened to one file.
+ *
+ * Three outcomes and not two, because "not imported" covers two different situations a person needs
+ * to tell apart: a file Quire deliberately did not want (an asset already inlined, a Notion index
+ * page that duplicates the folder) is `skipped`, and a file that should have become a page and did
+ * not is `failed`. Collapsing them turns a broken import into a tidy-looking one.
+ */
+export const ImportOutcome = z.enum(['imported', 'skipped', 'failed'])
+export type ImportOutcome = z.infer<typeof ImportOutcome>
+
+/**
+ * One row of the report: what the file was, what became of it, and which.
+ *
+ * The failure list is the feature. A real Notion export has files that will not map, and an import
+ * that silently drops forty pages is worse than one that refuses — so every file in the upload gets
+ * an entry, including the ones that worked, and the report is complete rather than a list of
+ * complaints. `path` is the path inside the archive, which is what somebody has to go and look at.
+ */
+export const ImportReportEntry = z.object({
+  /** the file's path inside the uploaded archive, exactly as it appeared */
+  path: z.string(),
+  outcome: ImportOutcome,
+  /** the page it became, for `imported`; null for the other two */
+  pageId: Id.nullable().default(null),
+  /**
+   * Why, for `skipped` and `failed`; null for `imported`.
+   *
+   * Free text on purpose: the reasons are as varied as the exports people have, and a closed enum
+   * here would either be wrong within a week or force every unexpected file into an `other` that
+   * tells nobody anything.
+   */
+  reason: z.string().nullable().default(null),
+})
+export type ImportReportEntry = z.infer<typeof ImportReportEntry>
+
+/**
+ * A Notion export zip, a Confluence export or a folder of Markdown, on its way into one space.
+ *
+ * `sourceFileId` is the upload, not an artefact — the opposite direction from `ExportJob.fileId`, and
+ * named differently for that reason. An import produces pages, not a file.
+ *
+ * Internal links between imported pages are rewritten to Quire page ids as the import goes; a link
+ * that cannot be resolved becomes plain text rather than a dead link, and the page that carried it
+ * still counts as `imported`. That choice is why `report` is per *file* and not per *link*: a page
+ * that arrived with one unresolvable link is an imported page, not a failure.
+ */
+export const ImportJob = z.object({
+  id: Id,
+  workspaceId: WorkspaceId,
+  requestedBy: UserId,
+  source: ImportSource,
+  /** the space being written into. An import always targets one space; there is no scope here. */
+  targetId: Id,
+  /** the uploaded archive — consumed by the job, and present before the job exists */
+  sourceFileId: Id,
+  state: TransferState,
+  /** why the *job* failed; why one *file* failed is that file's entry in `report` */
+  error: z.string().nullable(),
+  counts: TransferCounts,
+  /** one entry per file in the upload, in the order they were read */
+  report: z.array(ImportReportEntry),
+  createdAt: Timestamp,
+  /** null while `queued` or `running` */
+  finishedAt: Timestamp.nullable(),
+})
+export type ImportJob = z.infer<typeof ImportJob>
+
 export const Ok = z.object({ ok: z.literal(true) })

package/src/contract/permissions.ts

@@ -64,6 +64,56 @@ export const quirePermissions = definePermissions([
     defaultRoles: ['owner', 'admin', 'member'],
     dangerous: false,
   },
+  /**
+   * Taking pages out of Kern as a file.
+   *
+   * A separate key from `quire.page.view` rather than a consequence of it, and the distinction is
+   * one administrators actually make: reading a handbook a page at a time and walking out with the
+   * whole thing in a zip are different acts, and the second is the one a leaver does on their last
+   * afternoon. Every page in an export is still checked against `quire.page.view` as it is written,
+   * so this grants nothing extra — it decides whether the bulk shape is available at all.
+   *
+   * Not `dangerous`, because it destroys nothing and every page in the result is one the exporter
+   * could already open. The import side is the dangerous half: that one writes.
+   *
+   * A guest is deliberately not in the default set. A guest is somebody invited to read one thing,
+   * and the difference between reading it and keeping a copy of the section around it is exactly
+   * what a guest is a guest for.
+   */
+  {
+    key: 'quire.page.export',
+    label: 'Export pages',
+    description: 'Take a page, a section or a space out as Markdown, HTML or PDF',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin', 'member'],
+    dangerous: false,
+  },
+  /**
+   * Bringing pages in from somewhere else, in bulk.
+   *
+   * **`dangerous`, where the export half is not**, and the asymmetry is the whole reason this is a
+   * separate key rather than `quire.page.create` applied a thousand times. An export reads pages the
+   * exporter could already open; an import *writes* — hundreds of pages, a page tree, databases with
+   * their columns — into a space, in one act, from a file nobody in the workspace has read. Undoing
+   * it means finding every page it made and trashing them, which is not a button. The tracker marks
+   * `tracker.import.run` the same way and for the same reason.
+   *
+   * Owner and admin only, and that is a deliberate step up from `quire.page.create`. Somebody who may
+   * write in a space is not thereby somebody who may reshape it: an ordinary member creating pages
+   * makes them one at a time, with the tree in front of them.
+   *
+   * It is not a substitute for the narrower keys. An import still writes only where the requester
+   * holds this permission *on that space*, and the job re-asks when it runs rather than trusting the
+   * answer from when it was queued — a permission taken away between the two is a job that fails.
+   */
+  {
+    key: 'quire.page.import',
+    label: 'Import pages',
+    description: 'Bring a Notion, Confluence or Markdown export into a space as pages',
+    scope: 'space',
+    defaultRoles: ['owner', 'admin'],
+    dangerous: true,
+  },
   {
     key: 'quire.page.delete',
     label: 'Delete pages permanently',
@@ -205,6 +255,40 @@ export const quireProcedureAuthz: Record<string, ProcedureAuthz> = {
   'databases.removeView': { check: 'page', permission: 'quire.page.edit' },
   'databases.setRelation': { check: 'page', permission: 'quire.page.edit' },
 
+  /*
+   * `start` is declared `page` because that is the branch that can be bound narrowly and therefore
+   * the branch worth proving: a `page` or `subtree` export resolves the target page's own ancestor
+   * chain and asks about it, so a page-scoped DENY of `quire.page.export` refuses the export of that
+   * page and of any section containing it. A `space` export has no one page to resolve — it is the
+   * whole space — so that branch asks the same permission at space scope, which is the narrowest
+   * scope that exists for it. `export.int.test.ts` covers the space branch against a space-scoped
+   * DENY, because the sweep in `authz.int.test.ts` only ever sends the page branch.
+   *
+   * `get` and `list` are `workspace` for the same reason `favorites.list` is: "my own exports" has
+   * no narrower scope. What keeps them private is not a permission at all but the `requested_by`
+   * filter in the query — row-level security fences the tenant, and a tenant is not a person.
+   */
+  'exports.start': { check: 'page', permission: 'quire.page.export' },
+  'exports.get': { check: 'workspace', permission: 'quire.page.export' },
+  'exports.list': { check: 'workspace', permission: 'quire.page.export' },
+
+  /*
+   * `start` is `space` where its export counterpart is `page`, and the difference is not an
+   * oversight. An import has no page to be scoped to — it *creates* the pages — so the space it
+   * writes into is the narrowest scope that exists for it, and a space-scoped DENY of
+   * `quire.page.import` is what has to refuse it. The check is asked twice on purpose: once here,
+   * before a row is recorded, and again inside the job as the person who asked, because a job runs
+   * minutes later and a permission can be taken away in between.
+   *
+   * `get` and `list` are `workspace` for the same reason `exports.get` and `favorites.list` are:
+   * "my own imports" has no narrower scope. What keeps them private is the `requested_by` filter in
+   * the query rather than a permission — row-level security fences the tenant, and a tenant is not
+   * a person.
+   */
+  'imports.start': { check: 'space', permission: 'quire.page.import' },
+  'imports.get': { check: 'workspace', permission: 'quire.page.import' },
+  'imports.list': { check: 'workspace', permission: 'quire.page.import' },
+
   'publishing.publish': { check: 'page', permission: 'quire.page.publish' },
   'publishing.revert': { check: 'page', permission: 'quire.page.edit' },
 

package/src/contract/router.ts

@@ -3,7 +3,12 @@ import { z } from 'zod'
 import {
   CommentAnchor,
   CommentThread,
+  ExportFormat,
+  ExportJob,
+  ExportScope,
   Favorite,
+  ImportJob,
+  ImportSource,
   Label,
   LabelColour,
   Ok,
@@ -32,6 +37,22 @@ import {
 } from './properties.js'
 
 const ws = z.object({ workspaceId: WorkspaceId })
+
+/**
+ * What names the workspace in a **public** URL: its id or its slug.
+ *
+ * The address the share dialog copies is `/p/<workspace-slug>/<publication-slug>/`, because a uuid
+ * in a link somebody sends a colleague is a receipt rather than an address. Every `public.*`
+ * procedure still needs an id before it touches `mod_quire` — anonymous means no principal, not no
+ * tenant — so the slug is resolved at the one anonymous entry point and everything downstream is
+ * unchanged. Widened here rather than parsed in the handler because a `z.uuid()` rejects the slug
+ * before any handler runs, which is how this shipped answering 404 for its own published URLs.
+ */
+const WorkspaceSegment = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[0-9a-zA-Z][0-9a-zA-Z-]*$/, 'not a workspace id or slug')
 const t = (...tags: string[]) => ({ tags })
 
 /** The page fields a shortcut row draws, so a sidebar is one request rather than one per entry. */
@@ -168,6 +189,34 @@ export type PublicSearchHit = z.infer<typeof PublicSearchHit>
 
 export const PublicSitemapEntry = z.object({ path: z.string(), lastModified: Timestamp })
 
+/**
+ * An export job, plus the one thing that cannot be stored on it: a link to the artefact.
+ *
+ * `downloadUrl` is minted per request and is null in every state but `done`. It is composed here
+ * rather than written into `export_jobs` because a signed storage URL is the object's key, so a
+ * stored one is both an address that leaks the workspace and file uuids and an address that stops
+ * working an hour later — and, worse, a fence applied once at the moment the job finished rather
+ * than every time somebody asks. A subtree export flattens pages of different readerships into one
+ * file, so the moment of the fetch is the moment that has to be checked.
+ */
+export const ExportJobDetail = ExportJob.extend({ downloadUrl: z.string().nullable() })
+export type ExportJobDetail = z.infer<typeof ExportJobDetail>
+
+/**
+ * An import job **without its report**, which is the only shape a list can afford to carry.
+ *
+ * The report is one row per file, and a Notion export is thousands of files — so twenty jobs in a
+ * list is a response of megabytes to draw a table of dates and states. `get` carries the whole thing
+ * because that screen is somebody looking at one import and asking what happened to their files,
+ * which is the question the report exists to answer.
+ *
+ * Omitted rather than truncated on purpose. A report cut off at fifty rows is one that has quietly
+ * stopped being the complete account of the archive, and a person reading "23 skipped" beside a list
+ * of twelve would have no way to know which. Absent is a state a client can render; incomplete is not.
+ */
+export const ImportJobSummary = ImportJob.omit({ report: true })
+export type ImportJobSummary = z.infer<typeof ImportJobSummary>
+
 /**
  * One picture from a published page, **as bytes rather than as an address**.
  *
@@ -765,6 +814,120 @@ export const quireContract = {
       .output(z.object({ pageId: Id, excluded: z.boolean() })),
   },
 
+  /**
+   * Taking work out: a page, a page and everything under it, or a whole space, as a file.
+   *
+   * Three procedures and no fourth, which is the shape worth explaining. There is no `download`:
+   * `get` carries a `downloadUrl` it mints as it answers, so the permission is checked on the
+   * request that fetches the file rather than baked into a link that outlives the check. And there
+   * is no `cancel`: a job either finishes or fails, both terminal, and a cancel that races a worker
+   * writing an artefact is a way to end up with an object nothing points at.
+   *
+   * **What the artefact contains is decided by the job, not by the caller.** `start` names a scope
+   * and a format; every page under that scope is then checked against the requester's own
+   * `quire.page.view`, and a page they may not read is left out and counted in `skipped`. So a
+   * subtree export by somebody with a page-scoped DENY is a smaller file, not a refusal — and
+   * `counts.skipped` is how they find out, which is the difference between an export that is quietly
+   * missing pages and one that says how many.
+   *
+   * `format: 'docx'` is declared in `ExportFormat` and refused by `start` today: see the note in
+   * `services/export.ts` for what makes a *correct* Word file more than a matter of effort, and why
+   * a refusal is better than a document that may not open.
+   */
+  exports: {
+    /** Queue one. The answer is a row to watch, never the file — see the note above. */
+    start: baseContract
+      .route({ method: 'POST', path: '/exports', ...t('exports') })
+      .input(
+        ws.extend({
+          scope: ExportScope,
+          /** the page for `page` and `subtree`, the space for `space`; `scope` says which */
+          targetId: Id,
+          format: ExportFormat,
+        }),
+      )
+      .output(ExportJobDetail),
+    /** Where it has got to, and — once it is `done` — a link that is good for a few minutes. */
+    get: baseContract
+      .route({ method: 'GET', path: '/exports/{jobId}', ...t('exports') })
+      .input(ws.extend({ jobId: Id }))
+      .output(ExportJobDetail),
+    /**
+     * This person's own exports, newest first.
+     *
+     * Deliberately not the workspace's. Row-level security fences the tenant, which is not a privacy
+     * boundary, so the `requested_by` filter in the query is the only thing that keeps one person's
+     * export of the salary handbook out of everybody else's list — the same rule `favorites.list`
+     * and `recents.list` follow.
+     */
+    list: baseContract
+      .route({ method: 'GET', path: '/exports', ...t('exports') })
+      .input(ws.extend({ limit: z.number().int().min(1).max(50).default(20) }))
+      .output(z.array(ExportJob)),
+  },
+
+  /**
+   * Getting work in: a Notion export, a Confluence export or a folder of Markdown, into one space.
+   *
+   * **The failure list is the feature.** A real export has files that will not map — an attachment,
+   * a `.csv` with no header, a page whose link points outside what was exported — and an import that
+   * silently drops forty pages is worse than one that refuses. So every file in the archive gets a
+   * row in `report` saying whether it became a page, was deliberately left out, or could not be read,
+   * and `counts.total` is exactly the number of rows: nothing in the archive goes unaccounted for.
+   *
+   * Three things follow from the archive being read whole before anything is written, and each is
+   * worth knowing before reading the handlers:
+   *
+   *   - **an import is all or nothing.** A zip that fails half way leaves the space exactly as it
+   *     was, because the plan is built in memory and written in one transaction;
+   *   - **links between imported pages are rewritten to Quire page ids**, which needs every id to
+   *     exist before any body is resolved — a link to a page further down the archive is the normal
+   *     case, not the exception. A link that resolves to nothing becomes plain text rather than a
+   *     dead link, and the report names the target it could not find;
+   *   - **a `.csv` becomes a database with typed columns**, guessed from the values and reported.
+   *
+   * `quire.page.import` is `dangerous`, as the tracker marks its own imports: this is the one thing
+   * in the module that writes hundreds of pages into a space in one act, and it is not undone by
+   * pressing something.
+   */
+  imports: {
+    /**
+     * Queue one. The answer is a row to watch; nothing has been written to the space yet.
+     *
+     * `fileId` is an upload — a core file the browser has already put in place — and not the archive
+     * itself. A zip is up to a few hundred megabytes, which is a file to be uploaded and then named,
+     * never a request body.
+     */
+    start: baseContract
+      .route({ method: 'POST', path: '/imports', ...t('imports') })
+      .input(
+        ws.extend({
+          /** the space being written into; an import always targets exactly one */
+          spaceId: Id,
+          source: ImportSource,
+          /** the uploaded archive, and not something this job produces — see `ImportJob` */
+          fileId: Id,
+        }),
+      )
+      .output(ImportJob),
+    /** Where it has got to, and — once it has finished — what happened to every file in it. */
+    get: baseContract
+      .route({ method: 'GET', path: '/imports/{jobId}', ...t('imports') })
+      .input(ws.extend({ jobId: Id }))
+      .output(ImportJob),
+    /**
+     * This person's own imports, newest first, without their reports — see `ImportJobSummary`.
+     *
+     * Deliberately not the workspace's, for the same reason `exports.list` is not: row-level security
+     * fences the tenant, which is not a privacy boundary, so the `requested_by` filter in the query
+     * is the only thing that keeps one person's import out of everybody else's list.
+     */
+    list: baseContract
+      .route({ method: 'GET', path: '/imports', ...t('imports') })
+      .input(ws.extend({ limit: z.number().int().min(1).max(50).default(20) }))
+      .output(z.array(ImportJobSummary)),
+  },
+
   /**
    * The signed-out surface. **This is the only part of Kern with no principal behind it.**
    *
@@ -795,7 +958,7 @@ export const quireContract = {
       .route({ method: 'GET', path: '/public/{workspaceId}/{slug}', ...t('public') })
       .input(
         z.object({
-          workspaceId: WorkspaceId,
+          workspaceId: WorkspaceSegment,
           slug: Publication.shape.slug,
           token: z.string().max(4096).nullable().default(null),
         }),
@@ -811,7 +974,7 @@ export const quireContract = {
       .route({ method: 'GET', path: '/public/{workspaceId}/{slug}/page', ...t('public') })
       .input(
         z.object({
-          workspaceId: WorkspaceId,
+          workspaceId: WorkspaceSegment,
           slug: Publication.shape.slug,
           /** '' is the front page */
           path: z.string().max(1024).default(''),
@@ -832,7 +995,7 @@ export const quireContract = {
       .route({ method: 'GET', path: '/public/{workspaceId}/{slug}/search', ...t('public') })
       .input(
         z.object({
-          workspaceId: WorkspaceId,
+          workspaceId: WorkspaceSegment,
           slug: Publication.shape.slug,
           q: z.string().min(2).max(200),
           limit: z.number().int().min(1).max(50).default(20),
@@ -846,7 +1009,7 @@ export const quireContract = {
      */
     sitemap: baseContract
       .route({ method: 'GET', path: '/public/{workspaceId}/{slug}/sitemap', ...t('public') })
-      .input(z.object({ workspaceId: WorkspaceId, slug: Publication.shape.slug }))
+      .input(z.object({ workspaceId: WorkspaceSegment, slug: Publication.shape.slug }))
       .output(z.object({ entries: z.array(PublicSitemapEntry) })),
     /**
      * The one procedure here that never distinguishes one slug from another.
@@ -859,7 +1022,7 @@ export const quireContract = {
      */
     robots: baseContract
       .route({ method: 'GET', path: '/public/{workspaceId}/{slug}/robots', ...t('public') })
-      .input(z.object({ workspaceId: WorkspaceId, slug: Publication.shape.slug }))
+      .input(z.object({ workspaceId: WorkspaceSegment, slug: Publication.shape.slug }))
       .output(z.object({ indexable: z.boolean(), sitemapPath: z.string().nullable() })),
     /**
      * The bytes of one picture on a published page.
@@ -879,7 +1042,7 @@ export const quireContract = {
       .route({ method: 'GET', path: '/public/{workspaceId}/{slug}/asset', ...t('public') })
       .input(
         z.object({
-          workspaceId: WorkspaceId,
+          workspaceId: WorkspaceSegment,
           slug: Publication.shape.slug,
           asset: z.string().min(1).max(2048),
           token: z.string().max(4096).nullable().default(null),
@@ -891,7 +1054,7 @@ export const quireContract = {
       .route({ method: 'POST', path: '/public/{workspaceId}/{slug}/unlock', ...t('public') })
       .input(
         z.object({
-          workspaceId: WorkspaceId,
+          workspaceId: WorkspaceSegment,
           slug: Publication.shape.slug,
           password: z.string().min(1).max(200),
         }),