Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/design/03-domain-model/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,7 +366,7 @@ is in `layering.md`; this is the term-by-term catalogue.

- **Stack** — the root of an Alchemy program; a set of Resources deployed as a
unit. `Alchemy.Stack(name, { providers, state }, Effect.gen(…))`. `lower()`
emits one Stack for the whole app; `prisma-composer deploy <entry>` drives it over the
emits one Stack for the whole app; `prisma deploy <entry>` drives it over the
app module directly (no hand-written stack file, no config file — ADR-0003).
`→` **Topology / implicit root Module**.
- **Resource\<Type, Props, Attributes>** — a managed entity with a string type
Expand Down
11 changes: 6 additions & 5 deletions docs/design/10-domains/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,21 +6,22 @@ architecture/design phase that comes *after* the high-level model is settled.
- [`core-model.md`](core-model.md) — the complete class/data-structure design of
`@prisma/composer` and the target-pack contract, with `@prisma/composer-prisma-cloud` as
the worked instance.
- [`deploy-cli.md`](deploy-cli.md) — Prisma Composer's own deploy
entrypoint (`prisma-composer deploy` / `prisma-composer destroy`): the pipeline,
- [`deploy-cli.md`](deploy-cli.md) — Prisma Composer's deploy entrypoint
(`prisma deploy`, and the `destroy` operation): the pipeline,
Comment thread
wmadden-electric marked this conversation as resolved.
stages and container (Project/Branch) resolution, the pack CLI seam and
per-kind assembly contracts, and the error surface. Rests on ADR-0003 …
ADR-0006, ADR-0023, ADR-0024.
ADR-0006, ADR-0023, ADR-0024, ADR-0049 and ADR-0050.
- [`module-composition.md`](module-composition.md) — module boundaries
(deps/expose), forwarding, nesting, and the packaged reusable module. Rests
on ADR-0016.
- [`config-params.md`](config-params.md) — how service config is declared
(a caller-owned schema), carried through deploy, serialized to platform
storage by the target (over key/value string pairs), and read back at boot.
Rests on ADR-0018 and ADR-0019.
- [`local-dev.md`](local-dev.md) — the local dev loop (`prisma-composer dev`):
- [`local-dev.md`](local-dev.md) — the local dev loop (`prisma dev`):
the pipeline deltas vs deploy, the process table and supervisor, per-resource
stand-ins, value sourcing, and the dev error surface. Rests on ADR-0041.
stand-ins, value sourcing, and the dev error surface. Rests on ADR-0041 and
ADR-0050.

The settled high-level model is recorded in:

Expand Down
42 changes: 21 additions & 21 deletions docs/design/10-domains/core-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,17 +54,17 @@ glossary's Lowering — live in `/deploy`):
**`/control` is a shipped entry, not a reservation** (ADR-0017): every extension
exposes one, and it is where its heavy deploy-time code lives —
`@prisma/composer-prisma-cloud/control` exports `prismaCloud()`,
`@prisma/composer/node/control` exports `nodeBuild()`. Only
`prisma-composer.config.ts` imports those entries, and only the CLI loads that
file, so nothing an app's own import graph reaches can pull control-plane code
`@prisma/composer/node/control` exports `nodeBuild()`. Only the `composer`
section of `prisma.config.ts` imports those entries (ADR-0049), and app code
never imports that file, so nothing an app's own import graph reaches can pull control-plane code
into the runtime artifact. Core's own control-plane surface (`Load`, `configOf`)
is small and pure and still sits on `.`; the config *types* (`defineConfig`,
`ExtensionDescriptor`) live on `@prisma/composer/config`.

| Entry | Exports | Imports (weight) |
| --- | --- | --- |
| `@prisma/composer` | node factories (`service`, `resource`, `dependency`, `module`), `Load`, `configOf`, `hydrate`, `BuildAdapter` type, model types (incl. `Config`) | nothing |
| `@prisma/composer/config` | `defineConfig`, `PrismaAppConfig`, `ExtensionDescriptor`, `NodeDescriptor`, `PreflightInput`, `TeardownInput` — the types `prisma-composer.config.ts` is checked against (ADR-0017) | nothing (types + one identity function) |
| `@prisma/composer/config` | `defineConfig`, `PrismaAppConfig`, `ExtensionDescriptor`, `NodeDescriptor`, `PreflightInput`, `TeardownInput` — the types the `composer` section of `prisma.config.ts` is checked against (ADR-0017, ADR-0049) | nothing (types + one identity function) |
| `@prisma/composer/deploy` | `lower()`, `lowering()`, the SPI types (`ServiceLowering`, `Lowering`, `ApplicationDescriptor`, `ProvisionerDescriptor`, `LowerContext`, `Outputs`, `LoweredResult`, `DeployedEntity`), `Bundle`/`AssembleInput` (the assembler's contract, defined once here) | `alchemy`, `effect` |
| `@prisma/composer-prisma-cloud` | `compute()` (declares a service; carries `run`/`load`), `rawPostgres()` (`{ name }` identity or `{ client }` dependency, by argument shape) + `rawPostgresContract`, `http()` | `@prisma/composer` only |
| `@prisma/composer/arktype` | `secretString()` — the arktype spelling of a `SecretString` input leaf (ADR-0042). Opt-in: no other entry imports it, so a Zod app never loads arktype | `arktype` |
Expand Down Expand Up @@ -105,14 +105,14 @@ Who imports what, end to end:
bundles this file (their bundler, or `next build`) — the framework never touches it;
- the **deploy entry is the app module itself**: everything about the
*application* is still derived from the root node (ADR-0003).
`prisma-composer deploy <entry>` imports it and calls
`prisma deploy <entry>` imports it and calls
`@prisma/composer/deploy`'s `lower()` internally;
- the **`prisma-composer.config.ts`** at the app root carries the two things the
graph cannot yield — the **extension list** and the **state store** (ADR-0017).
The CLI finds it by walking up from the deploy entry and loads it with c12. It
is the only importer of the `/control` entries where heavy code lives, and app
- the **`composer` section of `prisma.config.ts`** carries the two things the
graph cannot yield — the **extension list** and the **state store** (ADR-0017,
ADR-0049). The Prisma CLI engine finds and loads the file, searching from the
command's working directory up to the repository root. The section is the only importer of the `/control` entries where heavy code lives, and app
code never imports it, which is what keeps that code out of the artifact. The
app author still writes no *stack* file — `prisma-composer deploy` generates one
app author still writes no *stack* file — `prisma deploy` generates one
at `.prisma-composer/alchemy.run.ts` per run and drives it; see
[`deploy-cli.md`](deploy-cli.md).

Expand Down Expand Up @@ -455,10 +455,10 @@ finds, deps before dependents.
import type { Layer } from "effect"
import type { Effect } from "effect"

// The config file's default export (ADR-0017). `prisma-composer.config.ts` sits at
// the app root and STATICALLY imports each extension's /control entry, so the
// framework never builds a module specifier, never resolves a path, and never
// imports by a computed name. Only the CLI loads it — app code never does, which
// The `composer` section of prisma.config.ts (ADR-0017, ADR-0049). The file
// STATICALLY imports each extension's /control entry, so the framework never
// builds a module specifier, never resolves a path, and never imports by a
// computed name. The Prisma CLI engine loads it — app code never does, which
// is what keeps control-plane code out of the runtime artifact.
interface PrismaAppConfig {
readonly extensions: ExtensionDescriptor[]
Expand Down Expand Up @@ -638,7 +638,7 @@ interface DeploymentResult {

interface LowerOptions {
readonly name: string // stack name (+ Load's root id override)
// `prisma-composer deploy` runs each service's build-adapter assembler and writes
// `prisma deploy` runs each service's build-adapter assembler and writes
// the resulting bundle dirs here, into the generated stack file it hands to
// `lower()` — one bundle per provision id (the deploy root is always a
// module). A hand-composed / mixed-stack caller (the escape hatch — see
Expand Down Expand Up @@ -965,7 +965,7 @@ const stash = (shape: readonly ConfigDeclaration[], config: Config): void => { /
```

Control entry (`@prisma/composer-prisma-cloud/control`) — the extension
descriptor `prisma-composer.config.ts` lists, and the only place `@internal/lowering`
descriptor the `composer` section of `prisma.config.ts` lists, and the only place `@internal/lowering`
is imported. Each node kind's hooks live in their own descriptor file; the
descriptor stitches them into one `nodes` registry:

Expand Down Expand Up @@ -1210,11 +1210,11 @@ Bun.serve({ port, hostname: "0.0.0.0",

// The app builds itself first (its own bundler produces dist/server.js), then:
//
// prisma-composer deploy src/module.ts
// prisma deploy src/module.ts
//
// The application is derived from the module root (ADR-0003); the extension list
// and state store come from prisma-composer.config.ts at the app root (ADR-0017),
// whose /control entries the CLI loads. It runs each service's assembly and drives
// and state store come from the `composer` section of prisma.config.ts (ADR-0017,
// ADR-0049), whose /control entries the CLI loads. It runs each service's assembly and drives
// Alchemy — no bundle map, no hand-written stack file.
```

Expand Down Expand Up @@ -1278,7 +1278,7 @@ export default module("storefront-auth", (h) => {
})

// No deploy config file (ADR-0003): build both apps, then
// prisma-composer deploy app.ts
// prisma deploy app.ts
```

At deploy, core sequences: the db resource (lowered once) → auth provision →
Expand Down Expand Up @@ -1326,7 +1326,7 @@ producer from a resource — one mechanism.
- **Build-adapter ecosystem** — `node` and `nextjs` are the first two; the
descriptor/assembler split is the seam for community adapters (Nuxt, TanStack
Start, a cron access-pattern, a static site). Each is a package the app lists in
its `prisma-composer.config.ts`; nothing in core, the prisma-cloud extension,
the `composer` section of its `prisma.config.ts`; nothing in core, the prisma-cloud extension,
`@internal/assemble`, or the CLI changes to add one — the assembler is a
`{ kind: "build" }` entry in the adapter's own `/control` registry, found by the
build descriptor's `(extension, type)` pair (ADR-0017), exactly like every other
Expand Down
Loading
Loading