Flatten repo so @corbits/artifacts is installable from git

Move the single package from packages/artifacts to the repository root so
`bun add github:corbitsdev/corbits-artifacts` resolves cleanly. Keep examples
as a workspace consumer; Bun installs from TypeScript sources via the bun
export condition, Node from built dist.

Closes CL-4792

Author: TheGreatAxios

.github/workflows/test.yml

@@ -39,15 +39,15 @@ jobs:
       # No unpublished @workbench/* scope may leak in — it does not exist on
       # npm, so a leak makes the package uninstallable outside the monorepo.
       - name: check-deps
-        run: bun run --cwd packages/artifacts scripts/check-deps.ts
+        run: bun run scripts/check-deps.ts
 
       # typecheck builds first: examples import @corbits/artifacts through the
       # published dist types, same path a consumer resolves.
       - name: typecheck
         run: bun run typecheck
 
       - name: unit + integration tests
-        run: bun run --cwd packages/artifacts test:coverage
+        run: bun run test:coverage
 
       # dist/ is already emitted by typecheck; re-run for a clean package build
       # so acceptance and the node consumer smoke test do not depend on typecheck
@@ -64,8 +64,8 @@ jobs:
       - name: node consumer smoke test
         run: |
           set -euo pipefail
-          TARBALL="$(cd packages/artifacts && npm pack --silent)"
-          TARBALL="$PWD/packages/artifacts/$TARBALL"
+          TARBALL="$(npm pack --silent)"
+          TARBALL="$PWD/$TARBALL"
           mkdir -p "$RUNNER_TEMP/consumer" && cd "$RUNNER_TEMP/consumer"
           npm init -y >/dev/null && npm pkg set type=module >/dev/null
           npm install "$TARBALL"

ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 How `@corbits/artifacts` is put together, and where its boundaries are. For
 install, the mount snippet, the route table and the response contracts, see the
-[package README](./packages/artifacts/README.md) — this document is about
+[package README](./README.md) — this document is about
 structure and reasoning, and does not repeat them.
 
 ## The shape of the thing

CHANGELOG.md

@@ -9,6 +9,14 @@ always called out under their own heading.
 
 ## [Unreleased]
 
+### Changed
+
+- The repository root **is** the `@corbits/artifacts` package. The previous
+  `packages/artifacts` workspace nesting is gone so
+  `bun add github:corbitsdev/corbits-artifacts` installs cleanly. Bun consumers
+  resolve TypeScript sources via the `bun` export condition; Node consumers
+  continue to use the built `dist/` from `npm pack` / a published release.
+
 ### 0.1.0 — first release
 
 Initial public release. Nothing has been published before this, so everything is

README.md

@@ -1,19 +1,253 @@
-# corbits-artifacts
+# @corbits/artifacts
 
-Home of **[`@corbits/artifacts`](./packages/artifacts)** — artifacts, versions
-and file uploads, mountable onto any Hono host on a shared or a separate database, with
-a pluggable `ContentStore` for where the bytes live. Backend only; this package ships
-no UI.
+Artifacts, versions and file uploads as a mountable module for any Interchange host.
+Backend only — this package ships no UI.
 
-See the [package README](./packages/artifacts/README.md) for install, the mount
-snippet and the mount options, and [ARCHITECTURE.md](./ARCHITECTURE.md) for the data model.
+`mountArtifacts(app, opts)` adds routes to a Hono app you already have. It never
+creates the app, opens a pool, or reaches for a session — the host owns all three and
+hands them in.
 
-## Layout
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for the data model, the mount options, and the
+design rationale behind them.
+
+## Requirements
 
 | | |
 | --- | --- |
-| `packages/artifacts` | The published package. Owns `artifact`, `artifact_version`, `upload` and `mail_attachment_ref`. |
-| `examples/reference-host` | Mounts it on a real `@intx/hub-api` app against a live Postgres and asserts the acceptance scenarios end to end. |
+| Runtime | Node 22+ or Bun 1.1+ |
+| Postgres | 13+ (`gen_random_uuid()`) |
+| Minimum `@intx/*` | **0.2.2** |
+
+Peer dependencies: `hono`, `hono-openapi`, `drizzle-orm`, `postgres`, `arktype`,
+`@intx/types`. They are peers rather than pinned deps because each is shared runtime
+state — a Hono app, a drizzle handle, a module-global registry — and a second copy in
+the tree does not error, it silently misbehaves.
+
+Your **host** additionally needs `@intx/hub-api`, `@intx/db`, `@intx/hub-sessions` and
+`@intx/hub-common` for `createApp`. This module imports none of them, so they are not
+peers here and npm will not warn you they are missing.
+
+## Install
+
+```bash
+# From git (Bun)
+bun add github:corbitsdev/corbits-artifacts
+
+# Or with peers explicitly
+bun add github:corbitsdev/corbits-artifacts \
+  hono hono-openapi drizzle-orm postgres arktype @intx/types@^0.2.2
+```
+
+```bash
+# npm / pack
+npm install @corbits/artifacts \
+  hono hono-openapi drizzle-orm postgres arktype @intx/types@^0.2.2
+```
+
+> **Not on npm yet.** Until the first release, consume it from git or an `npm pack`
+> tarball. The `@intx/*` packages *are* published, at `0.2.2`. This repository root *is*
+> the package, so git installs resolve cleanly.
+
+## Mount
+
+```ts
+import { Hono } from "hono";
+import type { AppEnv } from "@intx/hub-api";
+import {
+  InlineContentStore,
+  mountArtifacts,
+  runArtifactMigrations,
+  type ResolvedPrincipal,
+} from "@corbits/artifacts";
+
+// Boot-time, once. Idempotent — safe on every boot of every replica.
+await runArtifactMigrations(hub.db);
+
+const api = new Hono<AppEnv>();
+mountArtifacts(api, {
+  db: hub.db,
+  contentStore: InlineContentStore,
+  resolvePrincipal(ctx): ResolvedPrincipal | null {
+    const user = (ctx as Context<AppEnv>).get("user");
+    if (!user) return null;
+    return { tenantId: user.tenantId, principalId: user.id };
+  },
+});
+app.route("/api", api);
+```
+
+Routes are registered root-relative and served under `/api` — the prefix Interchange
+serves its own routes under. No `/v1`, no vendor prefix.
+
+`examples/reference-host` in this repository is a complete `@intx/hub-api` host with
+this module mounted and the acceptance suite pointed at it. Start there if you need the
+whole `createApp` wiring.
+
+## The options
+
+Three options have no sensible default; the rest fail closed and degrade a *feature*,
+never safety.
+
+| Option | Required | Default and what omitting it costs |
+| --- | --- | --- |
+| `db` | **yes** | The drizzle handle the host already has |
+| `contentStore` | **yes** | `InlineContentStore` for a minimal host |
+| `resolvePrincipal` | **yes** | `(ctx: unknown) => { tenantId, principalId } \| null`. Identical to `@corbits/mailbox-core`'s, so a host mounting both passes one function to both. The resolved tenant is authoritative — no caller-supplied override. |
+| `isAdmin` | no | Nobody is an admin — only the owner (and the member behind a producing agent) can archive. Nothing becomes more permissive. |
+| `identity` | no | `anonymousIdentity` — `ownerName` is `null`, `?creatorKind=` matches nothing, cross-tenant reads refused. |
+| `decorate` | no | No-op — rows carry no decoration. Display-only by contract, so it can never change what is returned or who sees it. |
+| `uploadPolicy` | no | `ARTIFACT_UPLOAD_POLICY` — the standard document/image/spreadsheet allowlist. |
+
+### Compatibility
+
+`MountArtifactsOpts` follows semver: breaking changes to option names or shapes only
+happen in major versions.
+
+## Routes
+
+| Surface | Behavior |
+| --- | --- |
+| `GET /api/artifacts` | Tenant-scoped list; query/kind/owner/creatorKind/date filters, keyset cursor, archived toggle. **Discovery only:** each item omits `content` (fetch bodies via detail, download, or tools) |
+| `POST /api/artifacts` | Human import — link a URL or paste text |
+| `POST /api/artifacts/upload` | multipart import. An optional `generatedBy` form field is stored as `source.generatedBy`, a free-form display label nothing here reads back |
+| `GET /api/artifacts/:id` | Deep link (archived artifacts still load) |
+| `GET`/`POST /api/artifacts/:id/versions` | Version history (paginated, no content bodies) and revision |
+| `POST /api/artifacts/:id/(un)archive` | Idempotent soft-hide |
+| `GET /api/artifacts/:id/download` | One path over three storage conventions |
+| `…/api/instances/:id/mail-attachments` | Artifact↔message associations |
+
+Every route carries `describeRoute`, so it appears in the host's `/openapi.json`.
+
+**List contract (minor client break):** `GET /api/artifacts` (and `listArtifacts` /
+`serializeArtifactListItem`) no longer include full `content` on each item. Clients that
+previously rendered list rows from the list payload must load bodies via
+`GET /api/artifacts/:id`, download, or the read tools. Search still matches title and
+content server-side; only the response projection changes.
+
+**Version history pagination:** `GET /api/artifacts/:id/versions` returns
+`{ versions, nextCursor }` with the same default/max limit clamps as list. Cursor is the
+last version number returned (newest-first). Version rows omit content; use
+`GET /api/artifacts/:id?version=N` (or `getArtifactVersion`) for a pinned body.
+
+**Write size limits:** create and revise reject titles longer than 512 characters and
+content larger than 15 MiB UTF-8 (`ArtifactSizeError` / HTTP 400). JSON mutators also
+refuse a declared `Content-Length` over that same 15 MiB ceiling with HTTP 413 before
+buffering the body; missing `Content-Length` still streams into the parser. **Hosts
+should set a global request body limit upstream** of this mount (Hono middleware, Bun
+server, reverse proxy) — the package check is a best-effort edge guard, not a substitute
+for a host-level cap. Upload byte caps remain on the multipart path.
+
+**Auth before body:** mutating JSON routes (`POST /api/artifacts`,
+`POST /api/artifacts/:id/versions`, `POST …/mail-attachments`) resolve the principal
+before parsing the body, so an unauthenticated caller gets 403 without learning whether
+the JSON was well-formed. Upload already auth'd first.
+
+### Two response contracts
+
+**No resolvable principal** — the cross-core rule every `@corbits/*` package follows, so
+a host mounting several hands its client one policy rather than three:
+
+| Route class | Response | In this core |
+| --- | --- | --- |
+| List / count / aggregate reads | **empty `200`** | `GET /api/artifacts` → `{"artifacts":[],"nextCursor":null}`; `GET …/mail-attachments` → `{"refs":[]}` |
+| Streams, detail reads, mutations | **`403`** | every other route |
+
+A collection read answers the truth and names no resource. Everything else names a
+specific resource, and whether it exists is not an unresolvable caller's to learn. This
+core exposes no stream today; the class is listed so a future one is classified by the
+rule rather than by guesswork.
+
+**Once a principal is resolved**, four causes collapse into one `404
+{"error":"Artifact not found"}` on all six single-artifact routes: the id was never
+minted, the id is not shaped like an id, the row is a `skill-draft`, or the row belongs
+to another tenant. A cross-tenant `403` would be an existence oracle — any account
+holder could walk ids and learn which name a real artifact somewhere in the deployment.
+
+Archive/unarchive still answer `403` for a caller who can see the artifact but may not
+administer it: an authorization decision about a row known to exist, not a disclosure.
+
+## Uploads: three allowlists, and who owns each
+
+Three surfaces mint file artifacts, each with its own explicit allowlist. Collapsing
+them into one global list would silently widen the narrow ones.
+
+| Policy | Surface | Owner |
+| --- | --- | --- |
+| `ARTIFACT_UPLOAD_POLICY` | Gallery import — `POST /api/artifacts/upload` | this package |
+| `SPREADSHEET_UPLOAD_POLICY` | Spreadsheet ingest | the host |
+| `PARSED_DOCUMENT_POLICY` | Chat/mail attachment divert | the host |
+
+What this package owns is the **gate**: `createFileArtifact` — the one function every
+file artifact goes through — takes `policy` as a required argument and refuses anything
+outside it with `UnsupportedUploadTypeError` before the `ContentStore` is touched. A
+host route cannot mint a file artifact without naming the surface it is minting it for.
+
+```ts
+// Parse BEFORE calling, so a parse failure leaves no orphan artifact.
+const parsed = await parseAttachment(file);
+try {
+  await db.transaction((tx) =>
+    createFileArtifact(tx, contentStore, {
+      scope,
+      ownerPrincipalId: scope.principalId,
+      filename: file.name,
+      mimeType: file.type,
+      bytes,
+      policy: PARSED_DOCUMENT_POLICY,
+    }),
+  );
+} catch (err) {
+  if (err instanceof UnsupportedUploadTypeError) return c.json({ error: err.message }, 415);
+  throw err;
+}
+```
+
+**File parsing is the host's, deliberately.** This package ships no PDF, spreadsheet or
+document text extractor and will not grow one: an extractor is a heavyweight fast-moving
+native dependency, and what the extracted text is *for* is the host's product. Of "parse
+a PDF and serve it inline", the inline half is ours and is covered by the acceptance
+suite. The contract owed to a parsing host is **parse before you store** — then a
+failure leaves no orphan artifact and no orphan bytes, and a success writes bytes, row
+and version 1 in one transaction.
+
+## ContentStore
+
+Where file bytes live is a port. Two impls ship and both pass the same suite:
+`InlineContentStore` (bytea side-table, referenced by `source.upload.id`) and
+`DataUrlContentStore` (bytes inline in `content` as a data: URL). An asset-substrate
+backend is a third impl, not a rewrite.
+
+The single download path resolves the conventions in precedence order — out-of-band
+blob, then inline data URL, then downloadable text (`csv-export`). Bytes are served as
+`attachment` with `X-Content-Type-Options: nosniff`, except a PDF requested `?inline=1`.
+
+## Schema and migrations
+
+Four tables — `artifact`, `artifact_version`, `upload`, `mail_attachment_ref` — in the
+package-owned `artifacts` Postgres schema. `tenant_id` is required (`NOT NULL`) and,
+with the principal columns, is a hard foreign key into Interchange's
+`public.tenant` / `public.principal`, so the host's own migrations must run first.
+Version columns CHECK ≥ 1; size columns CHECK ≥ 0. Whether a principal belongs to
+the stamped tenant is **host-owned** via `resolvePrincipal` — the package does not
+install multi-table triggers for that alignment (see ARCHITECTURE.md).
+
+`runArtifactMigrations(db)` is idempotent, advisory-locked, creates and owns the
+`artifacts` Postgres schema, and keeps its own ledger
+(`artifacts.migrations`). Call it unconditionally on every boot of every
+replica: concurrent cold starts serialize on a transaction-scoped advisory lock, and a
+re-run prints nothing.
+
+If the ledger is empty but package tables already exist (restored dump, dropped
+ledger), the runner fails closed with `MigrationAdoptError`. Operators who have
+confirmed the live schema may pass `{ adopt: true }` to record checksums without
+re-running DDL. Adopt validates tables, column types, `artifact.tenant_id NOT NULL`,
+and the named version/size CHECK constraints — not a columns-only glance.
+
+Event timestamps are `timestamptz` so list keyset cursors and date filters stay
+stable under a non-UTC session `TimeZone`. A ledgered retype migration converts
+legacy zoneless columns with `USING col AT TIME ZONE 'UTC'` (existing walls were
+always documented as UTC). Do not edit shipped migrations to roll back — ship a
+new reverse cast if you must.
 
 ## Working on it
 
@@ -26,10 +260,9 @@ docker run -d --name corbits-artifact-pg -p 5457:5432 \
 # Both refuse unless you opt in and the database name is allowlisted.
 export ALLOW_DESTRUCTIVE_ARTIFACT_TESTS=1
 
-bun run test:package     # dependency check, then unit + integration
+bun run test             # dependency check, then unit + integration
 bun run build            # dist/ (JS + .d.ts)
 bun run test:acceptance  # builds, then the acceptance scenarios
-bun run test             # both suites
 ```
 
 `test:acceptance` builds first because the reference host consumes the built `dist` the
@@ -40,16 +273,30 @@ Tests and the example expect
 `postgres://postgres:postgres@localhost:5457/artifact_core`; override with
 `ARTIFACT_DATABASE_URL`. Destructive package tests additionally require
 `ALLOW_DESTRUCTIVE_ARTIFACT_TESTS=1` and an allowlisted database name
-(`artifact_core`, or any name ending in `_test`). See the package README Development
-section for the full gate contract.
+(`artifact_core`, or any name ending in `_test`).
 
-## Conventions
+| Requirement | Value |
+| --- | --- |
+| Opt-in env | `ALLOW_DESTRUCTIVE_ARTIFACT_TESTS=1` (exactly `"1"`) |
+| Database name allowlist | `artifact_core` (the documented local docker default), **or** any name ending in `_test` (e.g. `artifacts_test`) |
+
+Point `ARTIFACT_DATABASE_URL` at an allowlisted ephemeral database. A missing opt-in
+or a production-looking name throws before any TRUNCATE/DROP runs. The gate is pure
+URL/env parsing, so its unit tests do not need a live Postgres.
+
+| | |
+| --- | --- |
+| `src/` | The published package. Owns `artifact`, `artifact_version`, `upload` and `mail_attachment_ref`. |
+| `examples/reference-host` | Mounts it on a real `@intx/hub-api` app against a live Postgres and asserts the acceptance scenarios end to end. |
 
 Strict TypeScript, arktype at boundaries, drizzle for data access. The package owns
-the `artifacts` Postgres schema — all four tables and the migration
-ledger live there, so sibling cores and host tables never collide.
-No `@workbench/*` imports anywhere — `scripts/check-deps.ts` fails the build on any
-import of that unpublished scope (it runs in `pretest` and CI).
+the `artifacts` Postgres schema — all four tables and the migration ledger live there,
+so sibling cores and host tables never collide. No `@workbench/*` imports anywhere —
+`scripts/check-deps.ts` fails the build on any import of that unpublished scope (it runs
+in `pretest` and CI).
+
+The tarball ships `src/` alongside `dist/`, so the emitted `.js.map` and `.d.ts.map`
+resolve: go-to-definition and stack traces land on real TypeScript.
 
 ## License