@geekmidas/manifest 9.0.2 → 10.0.0-alpha.1

package/dist/index.d.cts

@@ -1,22 +1,1071 @@
-//#region src/index.d.ts
+//#region src/declaration.d.ts
+/**
+ * The construct manifest — the contract between what an application declares
+ * and what a target adapter provisions.
+ *
+ * Kinds are added here as each one lands, not up front: a declaration for a
+ * construct nobody has built yet is a guess that the implementation will
+ * contradict. See `docs/design/constructs-paradigm.md`.
+ */
+/**
+ * A construct's canonical id — PascalCase, unique within the manifest.
+ *
+ * Inputs canonicalise, so `uploads`, `Uploads`, `user_uploads`, and
+ * `user-uploads` are the *same* id rather than four that collide. Everything
+ * else derives from it: the service key is its `Uncapitalize`, the env prefix
+ * its SCREAMING_SNAKE form, the cloud name its kebab form scoped by stage and
+ * app.
+ */
+type ConstructId = string;
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+/**
+ * Constrains a construct name at the point it is written.
+ *
+ * Resolves to the name itself when valid, and otherwise to a string explaining
+ * why — so the compiler reports *"not assignable to type 'a construct name
+ * cannot start with a digit'"* rather than the unhelpful `never`.
+ *
+ * Only the cases a template-literal type can see are caught here; `canonicalId`
+ * enforces the rest at runtime, which is also what covers JavaScript callers.
+ *
+ * @example new ObjectStorage('Uploads')  // ok
+ * @example new ObjectStorage('2fa')      // a construct name cannot start with a digit
+ */
+type ConstructName<S extends string> = S extends '' ? 'a construct name cannot be empty' : S extends `${Digit}${string}` ? 'a construct name cannot start with a digit' : S;
+/** Shared by every declaration. */
+interface Node {
+  id: ConstructId;
+  /**
+   * Env keys this construct resolves onto anything that depends on it.
+   * Names only — the values are composed by the adapter from the provisioned
+   * resource's own attributes.
+   */
+  provides?: readonly string[];
+  /**
+   * Env keys this construct needs. Derivable from `dependencies`, so it is an
+   * assertion rather than an input: the adapter composes env from the edges and
+   * checks the result against this, which catches app/infra drift at synth.
+   */
+  requires?: readonly string[];
+}
+/**
+ * A dependency edge. Records only *what* is depended on — never permissions.
+ * From one edge the framework derives env and the runtime binding; a target
+ * adapter separately derives cloud access.
+ */
+interface Dependency<TTarget extends ConstructId = ConstructId> {
+  /**
+   * The {@link ConstructId} of the consumed construct. Left open here because a
+   * declaration is written before the manifest that contains it; once assembled,
+   * `IdsOf` narrows it and the build's reference-integrity check enforces it.
+   */
+  target: TTarget;
+  kind: DeclarationKind;
+}
+/** Anything with a handler. */
+interface Fn extends Node {
+  handler: string;
+  dependencies: readonly Dependency[];
+}
+/** Blob storage. `--target=aws` provisions a bucket. */
+interface ObjectsDeclaration extends Node {
+  kind: 'objects';
+  versioned?: boolean;
+}
+/**
+ * A domain that serves a bucket's objects.
+ *
+ * Its own construct rather than a flag on the bucket, because three things it
+ * has to express are not properties of a bucket: a surface can front several
+ * origins, a bucket can have several surfaces over it, and issuing a
+ * certificate and writing a DNS record is a domain lifecycle that has no
+ * business living inside an `objects` provisioner. It shares its infrastructure
+ * with a static site rather than with storage — a site is the same
+ * distribution over a build output instead of over live contents.
+ *
+ * It derives from the bucket by `of`, which costs the one thing the flag gave
+ * for free: the bucket alone no longer says whether it is served, and finding
+ * out means finding whoever points at it. That is answered the way every other
+ * derivation is — the reference check at manifest build, so an unresolvable
+ * origin is a build failure and `gkm` can name, for any bucket, the surfaces
+ * over it.
+ *
+ * Private by default. `open` is an exception list, because a bucket where
+ * forgetting a flag publishes user uploads is the wrong default — and paths
+ * rather than per-object flags, because a path pattern is what the
+ * infrastructure actually enforces and a per-object ACL is a thing nobody
+ * audits.
+ *
+ * "Open" never means the bucket is world-readable. It means the server serves
+ * that path without a signature; the bucket is private in both cases.
+ */
+interface FileServerDeclaration extends Node {
+  kind: 'file-server';
+  /** The bucket whose objects it serves. */
+  of: ConstructId;
+  /**
+   * Paths served without a signature — everything else requires one.
+   *
+   * Globs, matched most-literally by the infrastructure: a CDN keys its
+   * behaviours off path patterns, and a bucket policy names prefixes.
+   */
+  open?: readonly string[];
+}
+/**
+ * Outbound email.
+ *
+ * Provides one `smtp://` URL and nothing else, because email is delivered over
+ * SMTP whatever the provider — Mailpit locally, SES through its SMTP interface,
+ * Resend and Postmark through theirs. There is no `provider` field here for the
+ * same reason there is no `ses://` scheme: which service delivers the mail
+ * differs between dev and prod, so by this design's own test it is stage-varying
+ * config rather than a structural fact about the app.
+ *
+ * What *is* structural is only that the app sends mail at all. The sending
+ * domain is not: it is `myapp.test` locally and `example.com` deployed, so it
+ * fails the same test the provider does and resolves at deploy alongside every
+ * other address.
+ */
+interface EmailDeclaration extends Node {
+  kind: 'email';
+}
+/**
+ * A logical database, its schema, and the roles that reach it.
+ *
+ * Provides one key — the *runtime* role's URL. The owner URL exists but is
+ * deliberately absent from `provides`: it is wired by the adapter straight into
+ * the migrator and seeder this construct declares, so no edge in any manifest
+ * can name it and nothing else can be granted it by mistake.
+ */
 /**
- * Deployment manifest types — the build output of `gkm build` that enumerates a
- * project's deployable units (routes, functions, crons, subscribers, queues)
- * with the metadata an infrastructure layer needs to provision them.
+ * The Postgres major versions this toolbox provisions.
  *
- * `gkm build` writes a single TypeScript module per provider
- * (`<out>/manifest/aws.ts`) of the form:
+ * A union rather than a string, because the two targets that read it are not
+ * equally forgiving: locally it becomes a container tag, where a typo yields a
+ * confusing pull failure, and on AWS it becomes an engine version, where a
+ * wrong value fails partway through a deploy. Both are better as a compile
+ * error.
+ *
+ * The union is what this toolbox knows how to name, not a promise that every
+ * target offers every one of them. A deployed stage is limited by the engine
+ * catalogue in its region, so check before pinning an unusual version:
+ *
+ * ```
+ * aws rds describe-db-engine-versions --engine postgres \
+ *   --query 'DBEngineVersions[].EngineVersion' --output text
+ * ```
+ *
+ * RDS offered 11 through 18 in `eu-west-1` when this was written. 11 and 12 are
+ * left out because they are past upstream end-of-life: still provisionable, but
+ * not something to make easy to reach for.
+ */
+type PostgresVersion = 13 | 14 | 15 | 16 | 17 | 18;
+/**
+ * The version used when a database names none.
+ *
+ * The point is not which number this is but that there is only one of them.
+ * Local ran 18 while Aurora provisioned its own default of 17.7, and nothing in
+ * any declaration recorded the difference — a stage could behave differently
+ * from a developer's machine for a reason neither could see. Both now read
+ * this.
+ */
+declare const DEFAULT_POSTGRES_VERSION: PostgresVersion;
+interface DatabaseDeclaration extends Node {
+  kind: 'database';
+  engine?: 'postgres';
+  /**
+   * The engine's major version, read by every target that provisions one.
+   *
+   * Declared rather than configured per target, because a version set in a
+   * compose file and a version set in a deploy config are two statements of
+   * one fact — and they had already drifted apart, silently, by a major.
+   *
+   * Defaults to {@link DEFAULT_POSTGRES_VERSION}.
+   */
+  version?: PostgresVersion;
+  /**
+   * The schema, pinned on both roles' `search_path`. Names the role the schema
+   * plays rather than restating the database's own name, so `app` reads
+   * correctly beside `auth` and `pgboss`.
+   */
+  schema?: string;
+  /**
+   * Whether to provision the owner/runtime role split. Off falls back to the
+   * cluster's master credential in both URLs — a deliberate downgrade, not a
+   * default. See `roles: false` in the design doc.
+   */
+  roles?: boolean;
+}
+/**
+ * A read-only endpoint on an existing database or schema.
+ *
+ * Provisions no cluster of its own — `of` names the parent it reads from.
+ * Read-only is enforced by the role's grants rather than by which endpoint it
+ * resolves to, so falling back to the writer where no replica exists stays safe.
+ */
+interface DatabaseReaderDeclaration extends Node {
+  kind: 'database-reader';
+  of: ConstructId;
+}
+/**
+ * A second schema inside an existing database, with its own role(s) and URL.
+ *
+ * The mechanism behind tenancy: the parent's role holds no grant on these
+ * tables at all. pg-boss is an instance of this rather than a special case.
+ */
+interface DatabaseSchemaDeclaration extends Node {
+  kind: 'database-schema';
+  of: ConstructId;
+  schema: string;
+}
+/**
+ * A generated secret — a signing key, a token, anything with no address.
+ *
+ * It provides a value rather than a URL, which is why it is a node of its own
+ * instead of a field on whatever needs it: the thing that generates it, the
+ * thing that stores it, and the thing that reads it are three different systems
+ * deployed, and one derived string locally.
+ */
+interface SecretDeclaration extends Node {
+  kind: 'secret';
+}
+/**
+ * A third-party credential with a shape.
+ *
+ * Distinct from {@link SecretDeclaration} by *lifecycle*, which is the only
+ * distinction worth having two kinds for. A secret is generated and rotated by
+ * the platform — `gkm secrets`, `sst secret set` — and is one opaque string
+ * whose name is its key. A credential is issued by someone else, arrives with
+ * several fields, and is validated on the way in: a Stripe key pair, an OAuth
+ * client, a webhook signing secret.
+ *
+ * It provides one key holding a JSON object, rather than one key per field.
+ * That is what a secret manager actually stores, and it is also the only shape
+ * that works with an arbitrary StandardSchema — the spec has no introspection
+ * API, so enumerating a schema's fields means reaching into one library's
+ * internals and being wrong for every other.
+ */
+interface CredentialDeclaration extends Node {
+  kind: 'credential';
+}
+/**
+ * An identity provider somebody else runs.
+ *
+ * Provisions nothing — the issuer already exists — so a target's whole job is
+ * to hand the process an issuer and an audience, and the verifier discovers the
+ * rest at runtime.
+ *
+ * It is a node rather than a field on whatever authenticates through it because
+ * two surfaces can name the same provider, and because *which* population a
+ * surface admits is a fact worth reading off the graph: an admin console
+ * authenticated by the customer auth server is a finding, and it is only
+ * visible if both are declarations.
+ */
+interface OidcDeclaration extends Node {
+  kind: 'oidc';
+  /**
+   * The issuer, when it does not vary by deployment.
+   *
+   * Absent means it arrives in the environment instead — a staging tenant, a
+   * per-customer directory. The audience is never here: it identifies one
+   * deployment to the provider.
+   */
+  issuer?: string;
+}
+/**
+ * A key/value cache.
+ *
+ * Provides one URL. What is *in* that URL is the backend's business — Upstash's
+ * REST API, a Redis endpoint, or a table in a database — and the scheme is what
+ * picks the client, exactly as it does for object storage.
+ *
+ * Two ways to declare one, and the difference is a real statement rather than a
+ * spelling. `new Cache('Sessions')` says *this app caches*, leaving where to the
+ * deployment; `orders.cache('Sessions')` says *this app caches in that
+ * database*, which is a fact about the application and belongs in its code. The
+ * second is the same strengthening `orders.schema('AuthDb')` is over declaring a
+ * second database.
+ */
+interface CacheDeclaration extends Node {
+  kind: 'cache';
+  /**
+   * The database this cache lives in, when it lives in one.
+   *
+   * Present only for a cache derived from a database. It removes a guess the
+   * backend selection otherwise has to make — "the declared database" is
+   * unambiguous with one and arbitrary with two — and it means the table's
+   * schema and the role that reaches it come from the parent rather than from
+   * a second convention.
+   */
+  of?: ConstructId;
+  /**
+   * The table entries are kept in, resolved against the connection's
+   * `search_path`. Defaults to `cache`.
+   */
+  table?: string;
+}
+/**
+ * An HTTP surface and the handlers mounted on it.
+ *
+ * The first kind that is not a resource in the ordinary sense: it owns an
+ * address, and the functions it triggers are *nested inside it* rather than
+ * listed beside it, because position carries the trigger — a handler here is
+ * reached by its method and path and by nothing else.
+ *
+ * `authorizers` are names. A bare string is resolved by the target (`iam`), while
+ * a {@link ConstructId} names a construct that carries its own implementation,
+ * its database dependency, and its session typing.
+ */
+interface RestApiDeclaration extends Node {
+  kind: 'rest-api';
+  /**
+   * Where the process serving it is built from, relative to the workspace
+   * root — the same thing a `site` says, for the same reason.
+   *
+   * A surface is a deploy unit: one of these is one server. Without it the
+   * deploy had to ask the *config* which apps to build, and a surface could
+   * never be its own process because it was not in that list. Two surfaces in
+   * one app then had to share one container, which is how an auth server ended
+   * up mounted into an API by a hook.
+   *
+   * Optional, and its absence is meaningful: a surface with no app of its own
+   * is served by the surface that named it — an auth server mounted into the
+   * API that called `.auth()` on it, rather than a second container nobody
+   * asked for.
+   */
+  app?: AppSpec;
+  /**
+   * The construct that authenticates this surface.
+   *
+   * An edge like any other — so the auth server learns this surface's origin,
+   * and the two share a cookie domain — but a *named* one, because "who
+   * authenticates me" is a different fact from "who I happen to call", and
+   * only one of them decides what a request is allowed to be.
+   *
+   * It is the id rather than the client: what every endpoint consumes is
+   * `verify(request) → Session | null`, and that is the one thing every
+   * provider shares. A surface names its authenticator; the target decides
+   * what verifying means.
+   */
+  auth?: ConstructId;
+  /**
+   * CORS tunables for this surface.
+   *
+   * *Who* may call it is never here — that is derived from the constructs
+   * declaring an edge to this surface, and arrives as `<ID>_TRUSTED_ORIGINS`.
+   * A hand-written origin list is the thing this model removes; these are the
+   * knobs that genuinely cannot be derived from a graph.
+   *
+   * Omitted entirely, a surface still gets CORS — with the derived origins and
+   * sensible defaults. There is nothing to opt into.
+   */
+  cors?: {
+    /** Preflight cache lifetime in seconds. Default 86400. */
+    maxAge?: number;
+    /** Whether the browser may send credentials. Default true. */
+    credentials?: boolean;
+    /** Extra request headers to allow, beyond content-type and authorization. */
+    allowHeaders?: readonly string[];
+    /** Response headers the browser may read. */
+    exposeHeaders?: readonly string[];
+  };
+  authorizers?: readonly string[];
+  /** The authorizer applied where an endpoint names none. */
+  defaultAuthorizer?: string;
+  /**
+   * Every route on this surface.
+   *
+   * Complete, always — a manifest that says "the routes are over there, run
+   * this glob to find them" is not a manifest, it is a pointer to one. An
+   * earlier version carried a `routes` glob for an application's own API and
+   * left this empty, which meant the document *claimed no routes* while five
+   * existed. Being incomplete is a gap; being wrong is worse.
+   *
+   * So a surface takes its endpoints as a list and reads method, path and
+   * handler off them. That also removes a duplicate: the glob was written once
+   * in `gkm.config.ts` and again on the construct, two strings that could
+   * disagree about the same thing.
+   */
+  endpoints: readonly RestApiEndpoint[];
+  /**
+   * Other surfaces this one calls.
+   *
+   * **Not a dependency, and deliberately not spelled like one.** A dependency
+   * is an injection: `resolveEdges` gives a function exactly the constructs it
+   * declared and nothing else, which is what makes least privilege fall out of
+   * the graph instead of out of discipline. A surface-level `dependencies`
+   * would hand *every route* on this API whatever the surface named — which is
+   * precisely the over-granting that rule exists to prevent.
+   *
+   * What this records is weaker and only flows one way: it puts this API's
+   * origin on the called surface's trusted-origin list. Nothing links from it,
+   * nothing is granted by it, and per-route edges stay on the endpoints where
+   * they belong.
+   */
+  calls?: readonly Dependency[];
+}
+/** One glob, or several. Mirrors the CLI's `Routes` without depending on it. */
+type Glob = string | readonly string[];
+/**
+ * How the process serving a declaration is built and run.
+ *
+ * The half of an application that a graph genuinely cannot derive. *What*
+ * exists — a surface, a site, the edges between them — is declared and read
+ * back from the manifest. *Where its source lives and which globs find its
+ * code* is not derivable from anything: it is a fact about a directory.
+ *
+ * It lives on the declaration rather than in a config `apps` block because the
+ * two were the same list written twice, and the copy in config was the one that
+ * could disagree. A site declared `path: 'apps/web'` and an app entry declared
+ * `path: 'apps/web'`, and nothing checked them against each other; a surface
+ * that config had no entry for simply never deployed.
+ *
+ * Only the declaration that *is* an app carries one. Two surfaces in one
+ * process means one of them has the spec and the other collapses onto it —
+ * which is the same rule that decides deploy units, now stated once.
+ */
+/**
+ * Where an app's code lives when nobody says otherwise.
+ *
+ * One glob, every kind — the same rule the `constructs` glob follows. A handler
+ * in one of these directories is found; anywhere else needs a `code` glob, and
+ * saying so is the whole reason the field still exists.
+ */
+declare const DEFAULT_APP_CODE = "./{endpoints,functions,crons,queues,topics,subscribers}/**/*.ts";
+interface AppSpec {
+  /**
+   * Where its source lives, relative to the workspace root.
+   *
+   * Optional, and normally omitted: `apps/<kebab-id>` when that directory
+   * exists, and the workspace root otherwise. An `Api` construct in a
+   * monorepo means `apps/api`, and in a single-app project it means `.` —
+   * both of which are answerable by looking, which is why neither was worth
+   * making someone write down.
+   *
+   * Set one only when the layout is genuinely different, e.g.
+   * `path: 'services/api'`.
+   */
+  path?: string;
+  /**
+   * The port it answers on locally.
+   *
+   * Optional, and normally omitted: ports are assigned in a stable order so
+   * that adding a site does not renumber the others. Set one only when
+   * something outside the workspace has to know it in advance.
+   */
+  port?: number;
+  /**
+   * One glob that finds everything this app defines, relative to `path`.
+   *
+   * Every export of every matching module is inspected, and each kind is
+   * picked out by whatever recognises it — the same rule the `constructs`
+   * glob already follows. A glob per kind was the specialness this model
+   * removes: five patterns that had to be kept in step, where a handler in the
+   * wrong directory simply never loaded and nothing said so.
+   *
+   * The per-kind fields below still work, and still win where both are given,
+   * because a single-app `defineConfig` has always been written that way.
+   *
+   * Optional, and normally omitted: the conventional directories under
+   * `path`, which is `DEFAULT_APP_CODE`. A glob is worth writing only when
+   * the code is somewhere else.
+   */
+  code?: Glob;
+  /** Globs that find one kind of thing. Prefer `code`. */
+  routes?: Glob;
+  functions?: Glob;
+  crons?: Glob;
+  queues?: Glob;
+  topics?: Glob;
+  subscribers?: Glob;
+  /** `./config/env#envParser` — module, optionally with an export. */
+  envParser?: string;
+  logger?: string;
+  telescope?: string | boolean | Record<string, unknown>;
+  studio?: string | boolean | Record<string, unknown>;
+  openapi?: boolean | Record<string, unknown>;
+  runtime?: 'node' | 'bun';
+  /** Env files to load, in order. */
+  env?: Glob;
+  /** Entry module for an app the build does not generate. */
+  entry?: string;
+  /** Modules to import when sniffing which env vars a frontend reads. */
+  config?: {
+    client?: string;
+    server?: string;
+  };
+}
+/**
+ * A frontend — a construct like any other, which is what removes the last
+ * mechanism that ran in parallel to the graph.
+ *
+ * Its edges are what make it worth declaring. A site depending on an API is the
+ * single fact behind four things that are hand-maintained otherwise: the site's
+ * build-time `VITE_API_URL`, the API's CORS origins, the auth server's trusted
+ * origins, and which generated client lands in which app. None of those are
+ * declared anywhere here, because all four are the *same* edge read from one
+ * end or the other.
+ *
+ * `variant` is the framework, because the framework changes the code you write:
+ * it selects how the values are delivered (`VITE_`, `NEXT_PUBLIC_`, a
+ * `config.json`), never which values there are.
+ */
+interface SiteDeclaration extends Node {
+  kind: 'site';
+  variant: 'static' | 'next' | 'tanstack';
+  /**
+   * How it is built and run, `path` included.
+   *
+   * Required, where a surface's is optional: a site is always its own app.
+   * There is no arrangement in which two sites are one process.
+   */
+  app?: AppSpec;
+  /**
+   * Whether this is the site the base domain points at.
+   *
+   * Structural rather than config: *which* site is primary does not vary by
+   * stage, even though its hostname does — that is what `app.domain` is for.
+   *
+   * Only meaningful when a project has more than one site, and then only when
+   * none of them is named `web`. The convention still holds first, because it
+   * is a convention people already rely on.
+   */
+  root?: boolean;
+  /**
+   * What it calls. On a node rather than on a handler because a site has no
+   * single entrypoint — the whole app is the consumer.
+   */
+  dependencies: readonly Dependency[];
+}
+/** One route on a surface. */
+interface RestApiEndpoint extends Fn {
+  method: string;
+  path: string;
+  authorizer?: string;
+}
+/**
+ * A point-to-point queue and the single consumer that drains it.
+ *
+ * Provides one key, the producer's connection string. The protocol in it picks
+ * the transport — `pgboss://` locally, `sqs://` deployed — so a producer names
+ * no broker, exactly as a database consumer names no cloud.
+ *
+ * The consumer side provides nothing: a worker is reached *through* its queue,
+ * so there is no second key and nothing can depend on a handler.
+ */
+interface QueueDeclaration extends Node {
+  kind: 'queue';
+  /** FIFO ordering, where the transport offers it. */
+  fifo?: boolean;
+  /**
+   * The single consumer that drains it.
+   *
+   * Nested rather than listed beside the queue, because **position carries the
+   * trigger**: a handler here is reached by messages arriving on this queue and
+   * by nothing else, so there is no `trigger` field to keep in step with it.
+   */
+  worker: Fn;
+}
+/**
+ * A topic — pub/sub fan-out, one publisher and any number of subscribers.
+ *
+ * Like a queue it provides only the producer's string; a subscriber is bound to
+ * the topic rather than depending on it, so the binding is an edge the deploy
+ * target reads, not an env key. Locally both sides meet on the same pg-boss
+ * connection, which is why the subscriber needs no key of its own.
+ */
+interface TopicDeclaration extends Node {
+  kind: 'topic';
+  /** The event type names this topic carries. */
+  events: readonly string[];
+  /**
+   * The handlers bound to it, each with the events it wants.
+   *
+   * Nested for the same reason a queue's worker is: position is the trigger. A
+   * subscriber is *bound* to a topic rather than depending on it, which is why
+   * it holds no key of its own and cannot be reached except through the topic.
+   */
+  subscribers: readonly (Fn & {
+    events: readonly string[];
+  })[];
+}
+/**
+ * A function invoked directly, with no surface in front of it.
+ *
+ * An `Fn` rather than a `Node`, because a function *is* a handler — there is no
+ * resource beside it to declare. It provides its own address, so something else
+ * can depend on it and be given a way to call it.
+ */
+interface FunctionDeclaration extends Fn {
+  kind: 'function';
+}
+/**
+ * A function on a schedule.
+ *
+ * The schedule is the trigger and it is structural: *that* something runs
+ * nightly is a fact about the application, while which timezone a stage
+ * interprets it in is not.
+ */
+interface CronDeclaration extends Fn {
+  kind: 'cron';
+  /** A rate or cron expression, e.g. `rate(1 day)`. */
+  schedule: string;
+}
+/**
+ * Every declaration. A discriminated union, so `kind` gives exhaustiveness *and*
+ * per-kind fields — there is no separate enum to keep in step, and no shape
+ * carrying fields that belong to a different kind.
+ */
+type Declaration = ObjectsDeclaration | FileServerDeclaration | EmailDeclaration | DatabaseDeclaration | DatabaseReaderDeclaration | DatabaseSchemaDeclaration | CacheDeclaration | SecretDeclaration | CredentialDeclaration | RestApiDeclaration | SiteDeclaration | OidcDeclaration | QueueDeclaration | TopicDeclaration | FunctionDeclaration | CronDeclaration;
+/** A declaration that provisions nothing of its own and names a parent. */
+/**
+ * A declaration that names a parent.
+ *
+ * A union rather than an `Extract`, because one kind is *optionally* derived: a
+ * cache lives in a database when it was declared from one and stands alone
+ * otherwise, so `of` is optional on it and an `Extract<…, { of: ConstructId }>`
+ * would not select it. {@link isDerived} tests the value rather than the kind
+ * for exactly that reason.
+ */
+type DerivedDeclaration = Extract<Declaration, {
+  of: ConstructId;
+}> | CacheDeclaration;
+type DerivedKind = DerivedDeclaration['kind'];
+/**
+ * What each kind may derive from.
+ *
+ * Small enough to state exhaustively, and stating it makes cycles impossible
+ * without a graph walk: readers are terminal, so no chain can return to its
+ * start. There is no `writer` — the database *is* the writer, which is what
+ * keeps a replica from being reached by accident.
+ */
+declare const DERIVES_FROM: Readonly<Record<DerivedKind, readonly string[]>>;
+type DeclarationKind = Declaration['kind'];
+/**
+ * The manifest: every construct keyed by its id.
+ *
+ * Flat rather than grouped, because `Dependency.target` resolves as
+ * `m[target]` — a lookup that stays O(1) and identical whether the edge points
+ * at a resource, a surface, or another function.
+ *
+ * Use it as a **constraint, not an annotation**. `gkm build` emits
+ * `as const satisfies ConstructManifest`, which checks the shape while keeping
+ * every id, kind, and provided key a literal — annotating with this type
+ * instead would widen them all to `string` and consumers could no longer select
+ * anything:
  *
  * ```ts
- * export const manifest = { routes: [...], functions: [...], ... } as const;
- * export type Route = (typeof manifest.routes)[number];
- * // ...derived types
+ * export const manifest = {
+ *   Uploads: { kind: 'objects', id: 'Uploads', provides: ['UPLOADS_URL'] },
+ * } as const satisfies ConstructManifest;
+ *
+ * type Ids = IdsOf<typeof manifest>;                       // 'Uploads'
+ * type Env = ProvidedKeys<typeof manifest, 'Uploads'>;     // 'UPLOADS_URL'
  * ```
+ */
+type ConstructManifest = Readonly<Record<ConstructId, Declaration>>;
+/** Every id in a manifest. */
+type IdsOf<M extends ConstructManifest> = Extract<keyof M, string>;
+/** The declaration for one id. */
+type DeclarationOf<M extends ConstructManifest, K extends IdsOf<M>> = M[K];
+/** Every id of a given kind — what an adapter iterates when provisioning. */
+type IdsOfKind<M extends ConstructManifest, K extends DeclarationKind> = { [Id in IdsOf<M>]: M[Id]['kind'] extends K ? Id : never }[IdsOf<M>];
+/** The env keys one construct provides. */
+type ProvidedKeys<M extends ConstructManifest, K extends IdsOf<M>> = M[K] extends {
+  provides: readonly (infer P)[];
+} ? P : never;
+/** Every env key any construct in the manifest provides. */
+type AllProvidedKeys<M extends ConstructManifest> = { [Id in IdsOf<M>]: ProvidedKeys<M, Id> }[IdsOf<M>];
+/**
+ * What each kind provides, by role rather than by provider syntax.
+ *
+ * This is the contract between the construct that declares a key and the cloud
+ * component that supplies its value — an interface rather than shared code,
+ * because a shared codec would have to contain `bucket` and `region`, and
+ * provider words in the neutral layer is the problem this design exists to fix.
+ *
+ * How a value is composed and parsed stays private to each provider pair, so
+ * `s3://` and `gs://` never appear here.
+ */
+interface ProvidesByKind {
+  objects: {
+    url: string;
+  };
+  /** Where the served objects answer. Public: a browser is the point of it. */
+  'file-server': {
+    url: string;
+  };
+  /**
+   * An `smtp://` URL, credentials included — never shippable — and the
+   * identity mail is sent from.
+   *
+   * The sending address is the one thing about mail that genuinely differs per
+   * stage (`myapp.test` locally, a verified domain deployed), so it travels
+   * beside the URL rather than being written into the construct.
+   */
+  email: {
+    url: string;
+    from: string;
+  };
+  /**
+   * One key, the runtime role's. The owner URL is not here by design — see
+   * {@link DatabaseDeclaration}.
+   */
+  database: {
+    url: string;
+  };
+  'database-reader': {
+    url: string;
+  };
+  'database-schema': {
+    url: string;
+  };
+  /** The endpoint and its token, in one string. */
+  cache: {
+    url: string;
+  };
+  /**
+   * Where the surface answers, who may call it, and the domain its cookies
+   * are scoped to.
+   *
+   * Only `url` is a fact about the surface itself. The other two are read off
+   * its *inbound* edges — every construct that depends on it — which is why a
+   * surface never lists its own callers: nothing enumerates the things that
+   * point at it, the graph already does.
+   *
+   * `trustedOrigins` and `cookieDomain` are one key each rather than a list
+   * and a structure, because both cross a process boundary as environment.
+   */
+  'rest-api': {
+    url: string;
+    /** Comma-separated. Empty when nothing declares an edge to this surface. */
+    trustedOrigins: string;
+    /**
+     * The parent domain shared by the surface and its callers, leading dot
+     * included — `.example.com`. Absent where there is nothing to share:
+     * one host locally, unrelated hosts deployed.
+     */
+    cookieDomain: string;
+  };
+  /** The value itself. A secret has no address to hand out instead. */
+  secret: {
+    value: string;
+  };
+  /**
+   * The credential as one JSON object, parsed and validated by the construct
+   * that declared the schema.
+   */
+  credential: {
+    credential: string;
+  };
+  /**
+   * The producer's connection string. One key, not two: the consumer is
+   * reached through the queue rather than by an address of its own.
+   */
+  queue: {
+    publisherConnectionString: string;
+  };
+  topic: {
+    publisherConnectionString: string;
+  };
+  /** Where to invoke it — what lets something else depend on a function. */
+  function: {
+    url: string;
+  };
+  /** A cron is reached by its schedule and by nothing else, so it provides none. */
+  cron: Record<never, never>;
+  /** Where the site is served. Public for the same reason an API's is. */
+  site: {
+    url: string;
+  };
+  /**
+   * Where tokens come from and which audience they must carry.
+   *
+   * Two keys because the halves have different lifetimes: the issuer may be a
+   * fact about the product, the audience is always a fact about one
+   * deployment.
+   */
+  oidc: {
+    issuer: string;
+    audience: string;
+  };
+}
+type Provides<K extends keyof ProvidesByKind> = ProvidesByKind[K];
+/**
+ * Which provided values may be shipped to a browser.
+ *
+ * Drives client-side prefixing (`VITE_`, `NEXT_PUBLIC_`) and nothing else — it
+ * is not a restriction on what may be depended on, since a server-side consumer
+ * can legitimately use any of them. A bucket's `url` presigns and stays private.
+ */
+declare const PUBLIC: { readonly [K in keyof ProvidesByKind]: readonly (keyof ProvidesByKind[K])[] };
+//#endregion
+//#region src/derive.d.ts
+/** Whether a declaration names a parent. */
+declare function isDerived(declaration: Declaration): declaration is DerivedDeclaration & {
+  of: ConstructId;
+};
+/**
+ * Check every derived construct against its parent.
+ *
+ * Two rules: the parent exists, and its kind may vend this one. Together they
+ * make cycles unreachable — a reader is terminal, so no chain of `of` can
+ * return to where it started, and no walk is needed to prove it.
+ */
+declare function assertDerivations(manifest: ConstructManifest): void;
+/**
+ * The order constructs must be provisioned in: every parent before its children.
+ *
+ * Resources are leaves and so come first in any order; only derived nodes
+ * constrain the sequence, and they form a shallow forest rather than a general
+ * graph. This walks each node's ancestors on demand instead of running a full
+ * topological sort, which is the same result at this depth and reads as what it
+ * is.
+ *
+ * Assumes {@link assertDerivations} has passed — a missing parent would
+ * otherwise be a silent omission here rather than an error.
+ */
+declare function provisionOrder(manifest: ConstructManifest): string[];
+/**
+ * Every edge a declaration carries, wherever the kind happens to keep them.
+ *
+ * Dependencies live in two places by design: on a node when the whole construct
+ * is the consumer (a site), and on each nested handler when the construct is a
+ * surface (a `rest-api`, whose routes each depend on their own things and
+ * nothing more). Flattening that difference here is what lets every consumer of
+ * the graph — reverse lookups, filtering, reference checks — ask one question.
+ */
+declare function dependenciesOf(declaration: Declaration): readonly Dependency[];
+/**
+ * The ids that depend on one construct — the graph read backwards.
+ *
+ * This is the whole mechanism behind CORS origins and trusted origins. Both are
+ * lists of *callers*, and a caller is exactly an inbound edge, so neither is
+ * ever written down: a surface that listed its own callers would have to be
+ * edited every time something new called it, which is the hand-maintained list
+ * this replaces.
+ *
+ * Sorted, because it feeds a comma-separated env value that would otherwise
+ * change whenever the manifest's key order did — and a value that churns is a
+ * container that redeploys for no reason.
+ */
+declare function dependentsOf(manifest: ConstructManifest, id: ConstructId): string[];
+/**
+ * How each site variant names a value it ships to the browser.
+ *
+ * The prefix *is* the framework's contract — `VITE_`, `NEXT_PUBLIC_` and
+ * `EXPO_PUBLIC_` all mean "inline this into the bundle" — so it is the one thing
+ * a variant changes, and it changes nothing else.
+ */
+declare const PUBLIC_PREFIX: Record<SiteDeclaration['variant'], string>;
+/**
+ * The keys a site's bundle needs, mapped to the key each value comes from —
+ * `{ VITE_API_URL: 'API_URL' }`.
+ *
+ * A rename, not a second derivation: `API_URL` is resolved once, by whatever
+ * resolved it for the server, and the site reads the same value under the name
+ * its bundler will inline. That is what keeps a site and its API from coming to
+ * disagree about where the API is.
+ *
+ * Filtered by `PUBLIC` rather than by what the site asked for. A site may
+ * legitimately depend on anything — its server half, where it has one, reads env
+ * exactly as a function does — so this is not a restriction on edges. It decides
+ * one thing: which values may be prefixed into a bundle, which is what keeps
+ * `ORDERS_URL` and its password out of a JavaScript file served to the public.
+ *
+ * Shared by every target for the same reason `providedKeyFor` is: a site built
+ * locally and the same site built by a deploy must inline the same names.
+ */
+declare function publicEnvFor(declaration: SiteDeclaration, manifest: ConstructManifest): Record<string, string>;
+//# sourceMappingURL=derive.d.ts.map
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Manifest errors.
  *
- * This is the dependency-free data contract shared between the producer
- * (`@geekmidas/cli`) and consumers (e.g. `@geekmidas/cloud/sst`'s `fromManifest`
- * integrators).
+ * Messages state the rule, which is constant; the offending value is a field.
+ * An interpolated message cannot be matched on, reads differently every time it
+ * is thrown, and carries user input into every log line that touches it.
  */
+/** A construct id that cannot survive the names derived from it. */
+declare class InvalidConstructId extends Error {
+  /** What was passed in. */
+  readonly input: string;
+  /** What canonicalising it produced, which is what failed the rule. */
+  readonly canonical: string;
+  constructor(input: string, canonical: string);
+}
+/** A derived construct naming a parent the manifest does not contain. */
+declare class UnknownParent extends Error {
+  /** The derived construct. */
+  readonly id: string;
+  /** The parent it named. */
+  readonly of: string;
+  /** Ids the manifest does contain, for the caller to match against. */
+  readonly available: readonly string[];
+  constructor(id: string, of: string, available: readonly string[]);
+}
+/**
+ * A derived construct naming a parent that may not vend it — a reader of a
+ * reader, a schema of a schema.
+ */
+declare class IllegalDerivation extends Error {
+  readonly id: string;
+  readonly kind: string;
+  /** The kind of the parent it named. */
+  readonly parentKind: string;
+  /** The parent kinds that may vend this one. */
+  readonly allowed: readonly string[];
+  constructor(id: string, kind: string, parentKind: string, allowed: readonly string[]);
+}
+//# sourceMappingURL=errors.d.ts.map
+//#endregion
+//#region src/naming.d.ts
+/**
+ * `UPPER_SNAKE_CASE`, with numbers kept against the word they follow.
+ *
+ * Matches `environmentCase` in `@geekmidas/envkit`, which reads the values these
+ * names key. The two must agree exactly, so this is the implementation and that
+ * one should defer to it.
+ *
+ * @example environmentCase('sendEmail') // 'SEND_EMAIL'
+ * @example environmentCase('api2')      // 'API2'  (digit joins its word)
+ */
+declare function environmentCase(name: string): string;
+/**
+ * The env key a construct provides for one of its roles.
+ *
+ * @example provideKey('Uploads', 'url')      // 'UPLOADS_URL'
+ * @example provideKey('Uploads', 'cdnUrl')   // 'UPLOADS_CDN_URL'
+ */
+declare function provideKey(id: string, role: string): string;
+/**
+ * A construct's canonical id — PascalCase.
+ *
+ * `uploads`, `Uploads`, `user_uploads`, and `user-uploads` all canonicalise to
+ * the same id, so declaring two of them is a duplicate rather than a collision
+ * to detect.
+ *
+ * Runtime only. Writing the id in PascalCase is what keeps the *type* usable:
+ * the service key is `Uncapitalize<TName>`, a TypeScript intrinsic, so no
+ * type-level transform is needed and none has to be kept in step with this one.
+ *
+ * @example canonicalId('user-uploads') // 'UserUploads'
+ */
+declare function canonicalId(input: string): string;
+/**
+ * The key a construct is reached under in the service record.
+ *
+ * The runtime twin of `Uncapitalize<TName>`, which types it — they must agree,
+ * so they live next to each other rather than being re-derived by each
+ * construct.
+ *
+ * @example serviceKey('UserUploads') // 'userUploads' → services.userUploads
+ */
+declare function serviceKey(id: string): string;
+/**
+ * The table a cache keeps its entries in, when nobody named one.
+ *
+ * Derived from the cache's own id rather than fixed at `cache`, because a
+ * database may hold more than one and two caches sharing a table share a
+ * keyspace — `orders.cache('Sessions')` and `orders.cache('Rates')` would
+ * silently read each other's entries and evict each other's keys.
+ *
+ * Prefixed rather than suffixed so every cache sorts together in `\dt`, and
+ * prefixed at all so a cache named for a thing the application also stores —
+ * `orders.cache('Users')` — cannot collide with the table holding that thing.
+ *
+ * Read by whoever composes the URL and by whoever creates the table, so both
+ * default the same way.
+ *
+ * @example cacheTable('Sessions') // 'cache_sessions'
+ */
+declare function cacheTable(id: string): string;
+/**
+ * Kebab-cases an identifier, acronym- and digit-aware.
+ *
+ * `userName` → `user-name`, `APIKey` → `api-key`, `S3Bucket` → `s3-bucket`.
+ *
+ * The last of those is why this is here rather than `snakecase(id)` with the
+ * underscores swapped: lodash splits a digit from the letter beside it, so
+ * `S3Bucket` became `s-3-bucket` on one provider and `s3-bucket` on the other.
+ * Two implementations of one rule, agreeing on every id anybody had tried.
+ *
+ * `environmentCase` already corrected for the same thing in the other
+ * direction — `api2` keeps its digit — so the two spellings of "kebab this id"
+ * in this file did not even agree with each other.
+ */
+declare function kebabCase(value: string): string;
+/**
+ * The physical name a target provisions a construct under — lowercase kebab,
+ * scoped so two stages or apps sharing an account cannot collide.
+ *
+ * **One rule, every provider.** A construct is named the same thing on AWS and
+ * on Dokploy, which is what lets a name be read across them: `Database` in the
+ * `production` stage of `kitchen-sink` is `production-kitchen-sink-database`
+ * wherever it lands. The SST target's `prefixedName` is this function under
+ * another signature and defers to it.
+ *
+ * Idempotent in its prefix: an id that already carries the scope is not given a
+ * second one, so composing names cannot double up.
+ *
+ * @example cloudName({ stage: 'prod', app: 'myapp' }, 'UserUploads')
+ * //        'prod-myapp-user-uploads'
+ */
+declare function cloudName(scope: {
+  stage: string;
+  app: string;
+}, id: string): string;
+/**
+ * {@link cloudName} for a caller that holds its scope as a list.
+ *
+ * The SST target's stacks add a segment of their own, so the prefix is not
+ * always two parts — which is the only reason this signature exists.
+ */
+declare function scopedName(scope: readonly string[], id: string): string;
+/**
+ * The domain a cookie must be scoped to so a surface and its callers share it.
+ *
+ * Derived from the addresses rather than configured, for the same reason the
+ * origins are: the set of things that talk to a surface is already in the graph,
+ * and the domain they have in common is a fact about that set. Returned with the
+ * leading dot a `Domain` attribute wants.
+ *
+ * Returns `undefined` when there is nothing to scope, which is the common case
+ * and not a failure:
+ *
+ * - **One host.** Locally everything is `localhost` on different ports, and
+ *   cookies ignore the port — so a `Domain` would add nothing and `.localhost`
+ *   is not a domain a browser will accept.
+ * - **Nothing in common.** Unrelated hosts cannot share a cookie at all, and
+ *   emitting the longest common suffix anyway would be a value that silently
+ *   fails to set.
+ *
+ * **The public-suffix limit, stated rather than discovered.** Two apps on
+ * `a.vercel.app` and `b.vercel.app` share `.vercel.app`, which every browser
+ * rejects because it is a registrable suffix rather than a registrable domain.
+ * Resolving that correctly needs the Public Suffix List, which is a downloaded,
+ * expiring dataset — so this requires at least two labels and otherwise trusts
+ * the addresses, and the value stays overridable for the case it gets wrong.
+ */
+declare function cookieDomain(urls: readonly string[]): string | undefined;
+/**
+ * The env key a construct's provided role actually becomes.
+ *
+ * Almost always `provideKey(id, role)` — and `secret` is the exception, because
+ * a secret's *name* is its key: `Auth` signs with `AUTH_SECRET`, which is also
+ * what better-auth's own tooling looks for, and qualifying it by role would
+ * produce `AUTH_SECRET_VALUE`.
+ *
+ * It lives here rather than in each target because two targets deriving the
+ * same key separately is exactly the drift the app/infra contract check exists
+ * to catch — and a check deriving the key differently from the thing it checks
+ * cannot catch anything.
+ */
+declare function providedKeyFor(id: string, kind: DeclarationKind, role: string): string;
+//# sourceMappingURL=naming.d.ts.map
+//#endregion
+//#region src/index.d.ts
 /**
  * A manifest field is either a flat list or, when the build is partitioned
  * (e.g. by authorizer), an object keyed by partition name. Readonly-tolerant so
@@ -37,6 +1086,15 @@ interface RouteInfo {
   memorySize?: number;
   /** Required environment variables (a trailing `?` marks an optional var). */
   environment?: readonly string[];
+  /**
+   * The constructs this handler declared an edge to, by id.
+   *
+   * What `.dependsOn()` was given, carried through the build so the manifest
+   * records the edge rather than only its shadow. `environment` is that shadow —
+   * the keys the handler reads — and it cannot be turned back into edges, which
+   * is why both exist and only this one grants anything.
+   */
+  dependencies?: readonly string[];
   /** Authorizer name: `none`, `iam`, or a declared authorizer. */
   authorizer: string;
 }
@@ -47,6 +1105,15 @@ interface FunctionInfo {
   timeout?: number;
   memorySize?: number;
   environment?: readonly string[];
+  /**
+   * The constructs this handler declared an edge to, by id.
+   *
+   * What `.dependsOn()` was given, carried through the build so the manifest
+   * records the edge rather than only its shadow. `environment` is that shadow —
+   * the keys the handler reads — and it cannot be turned back into edges, which
+   * is why both exist and only this one grants anything.
+   */
+  dependencies?: readonly string[];
 }
 /** A scheduled (cron) function. */
 interface CronInfo {
@@ -57,6 +1124,15 @@ interface CronInfo {
   timeout?: number;
   memorySize?: number;
   environment?: readonly string[];
+  /**
+   * The constructs this handler declared an edge to, by id.
+   *
+   * What `.dependsOn()` was given, carried through the build so the manifest
+   * records the edge rather than only its shadow. `environment` is that shadow —
+   * the keys the handler reads — and it cannot be turned back into edges, which
+   * is why both exist and only this one grants anything.
+   */
+  dependencies?: readonly string[];
 }
 /** An event subscriber function (topic/queue resolved by `transport`). */
 interface SubscriberInfo {
@@ -70,6 +1146,15 @@ interface SubscriberInfo {
   timeout?: number;
   memorySize?: number;
   environment?: readonly string[];
+  /**
+   * The constructs this handler declared an edge to, by id.
+   *
+   * What `.dependsOn()` was given, carried through the build so the manifest
+   * records the edge rather than only its shadow. `environment` is that shadow —
+   * the keys the handler reads — and it cannot be turned back into edges, which
+   * is why both exist and only this one grants anything.
+   */
+  dependencies?: readonly string[];
 }
 /**
  * A pub/sub topic — fan-out. A *resource* (no handler): it declares the event
@@ -94,6 +1179,12 @@ interface QueueInfo {
   timeout?: number;
   memorySize?: number;
   environment?: readonly string[];
+  /**
+   * The constructs the worker declared an edge to, by id.
+   *
+   * See {@link RouteInfo.dependencies} — same field, same reason.
+   */
+  dependencies?: readonly string[];
 }
 /**
  * The full deployment manifest — the shape of `export const manifest` in a
@@ -109,6 +1200,7 @@ interface Manifest {
   topics?: ManifestField<TopicInfo>;
 }
 //# sourceMappingURL=index.d.ts.map
+
 //#endregion
-export { CronInfo, FunctionInfo, Manifest, ManifestField, QueueInfo, RouteInfo, SubscriberInfo, TopicInfo, flattenManifestField };
+export { AllProvidedKeys, AppSpec, CacheDeclaration, ConstructId, ConstructManifest, ConstructName, CredentialDeclaration, CronDeclaration, CronInfo, DEFAULT_APP_CODE, DEFAULT_POSTGRES_VERSION, DERIVES_FROM, DatabaseDeclaration, DatabaseReaderDeclaration, DatabaseSchemaDeclaration, Declaration, DeclarationKind, DeclarationOf, Dependency, DerivedDeclaration, DerivedKind, EmailDeclaration, FileServerDeclaration, Fn, FunctionDeclaration, FunctionInfo, Glob, IdsOf, IdsOfKind, IllegalDerivation, InvalidConstructId, Manifest, ManifestField, Node, ObjectsDeclaration, OidcDeclaration, PUBLIC, PUBLIC_PREFIX, PostgresVersion, ProvidedKeys, Provides, ProvidesByKind, QueueDeclaration, QueueInfo, RestApiDeclaration, RestApiEndpoint, RouteInfo, SecretDeclaration, SiteDeclaration, SubscriberInfo, TopicDeclaration, TopicInfo, UnknownParent, assertDerivations, cacheTable, canonicalId, cloudName, cookieDomain, dependenciesOf, dependentsOf, environmentCase, flattenManifestField, isDerived, kebabCase, provideKey, providedKeyFor, provisionOrder, publicEnvFor, scopedName, serviceKey };
 //# sourceMappingURL=index.d.cts.map