stitchkit 0.93.0 → 0.94.1

package/llms/declaration.txt

@@ -0,0 +1,286 @@
+# stitchkit/declaration — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: Guide: Project declaration  (docs/guide/declaration.md) · API reference: `stitchkit/declaration`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Project declaration  (docs/guide/declaration.md)
+==============================================================================
+
+---
+title: Project declaration
+description: One machine-readable statement a repository makes about itself — identity, roles, build, requirements, release steps and the names of the values a deployment supplies.
+type: architecture
+status: active
+created: 2026-08-25
+updated: 2026-08-30
+---
+
+# Project declaration
+
+> **Maturity: evolving.** This surface is still finding its shape and may be
+> redefined in any minor release — always with a `### ⚠️ Breaking changes` entry
+> and a migration section, never silently.
+
+> **Declaring yourself is optional.** A project with no `project.json` is a
+> complete stitchkit project: nothing in `stitchkit`, `stitchkit/server`,
+> `stitchkit/node`, `stitchkit/tools` or `stitchkit/cli` reads a declaration,
+> and no build, test or start path looks for one. Read this page as an offer,
+> not a requirement — it describes what you get if you decide to say these
+> things in a machine-readable way instead of in a README.
+
+`stitchkit/declaration` is the schema for what a repository says about itself:
+what it is, the roles it runs, what it builds, what has to exist before it
+starts, what must happen once on release, and the **names** of the environment
+variables a deployment has to supply.
+
+```ts
+import { parseProjectDeclaration } from 'stitchkit/declaration';
+import declaration from '../project.json';
+
+export const appDeclaration = parseProjectDeclaration(declaration);
+```
+
+`parseProjectDeclaration` checks `schemaVersion` **before** it reads any field.
+A reader that does not recognise the version refuses the repository instead of
+interpreting it partially — a half-understood declaration is the one failure
+mode that produces a running, wrong deployment rather than an error.
+
+## Why declare yourself
+
+### Identity is not product membership
+
+The exported names `ProjectDeclaration` and `ProjectIdentity` describe the buildable source/artifact
+declared by a repository. A singular `identity` does **not** make a product project and a repository
+the same entity, nor does it identify a local checkout or a harness session.
+
+| Entity | Meaning and owner |
+| --- | --- |
+| Product project | A product boundary whose repository membership is explicitly maintained outside this declaration |
+| Repository | Versioned source; its declaration describes roles, build outputs and release requirements |
+| Checkout | A local working copy of a repository revision; local paths and credentials belong to its host |
+| Harness workspace | The host-selected working scope for a session, not an implied product or membership registry |
+
+Membership is many-to-many. For example, an external registry may declare product A includes
+repositories `service-a` and `shared-library`, while product B includes `service-b` and the same
+`shared-library`. Both products can read the library's unchanged declaration. Installing that library
+as a dependency, placing a checkout beside another, or naming a harness workspace does not create
+membership. The embedding product/registry owns these explicit relationships and their access policy.
+
+A private companion repository can be part of a product without becoming a separate product. Its
+relationship and working context stay in an authorized private registry, never in a potentially public
+library declaration. No registry or membership fields are required here; the declaration remains
+optional. Existing exports and schema version 1 are unchanged.
+
+### One statement, several readers
+
+Because the statements exist either way, and without a schema they exist three
+times. A repository already says how many roles it runs (in a process file),
+which variables it needs (in a Zod schema), what it builds (in a script) and
+what has to happen on release (in a README paragraph). Those four copies drift
+independently, and nothing fails when they do.
+
+What a declaration buys:
+
+- **One reader can be outside the tree.** Whatever builds a source into an
+  artifact and binds that artifact into a deployment can validate the project
+  with the same schema the project validates itself with, without being told
+  anything by the author.
+- **The tool is not the format.** The schema ships from the framework and is
+  plain published TypeScript plus JSON. Any side may read `project.json`
+  through `stitchkit/declaration` — or generate a JSON Schema from it with
+  `z.toJSONSchema` — and serve the project without asking the format's author
+  for anything. A repository that only one specific tool can bring up is a fork,
+  not a dependency.
+- **Generated instead of hand-kept.** The starter renders its supervision files
+  and its client-safe identity module from the declaration, so a role added in
+  one place cannot be missing in another.
+
+What it does not buy: nothing here starts, supervises or deploys anything.
+The declaration is a statement; acting on it belongs to whatever brings a
+deployment to a source.
+
+## The boundary rule
+
+> A declaration must be complete and meaningful **when no machine exists**. A
+> field that cannot be filled in without knowing where the code will run is a
+> binding supplied by the deployment, not a declaration made by the repository.
+
+So ports, hosts, absolute URLs, connection strings, machine paths, routing
+shape, supervision policy and secrets are never *values* in a declaration. A
+binding is **named** — by the variable that will carry it — and never valued:
+
+```jsonc
+{
+  "listener": { "portVariable": "API_PORT", "bindVariable": "BIND_HOST", "readinessPath": "/health" }
+}
+```
+
+**What is guaranteed is structure**: there is nowhere in the declaration that a
+value of the place must go. A command is `executable` plus an `args` array — no
+shell string, no pipe — and no part may be an absolute path or carry an inline
+value, so `--port=8080` must be written `['--port', '8080']`, where it is
+refused as a port. A listener's variables must exist in `env.variables` with the
+right shapes. Unknown keys are refused rather than stripped.
+
+**What is filtered is the rest**: every remaining free string is checked against
+`namesAMachine` — a scheme, a protocol-relative host, an absolute or
+home-relative path, a Windows drive, a `host:port` pair, a bare IPv4 literal.
+
+The second half is hygiene, not a proof, and it is worth knowing where it stops:
+a secret written as its own argument and a hostname written as a plain word look
+like any other argument. The schema will not catch them, and it is not trying
+to — the point is that a complete declaration can be written before any machine
+exists, not that nobody can type a value into one.
+
+## Three kinds of input, not two
+
+The boundary rule separates code from the values of a place. There is a third
+kind that is neither: **data read while building**. Pages prerendered from a
+database depend on bytes that are not in the source and are not a binding, and
+moving environment variables around does not make such a build portable.
+
+Decide it **per route**, not per project:
+
+| what the bytes depend on | what is legitimate |
+| --- | --- |
+| only the source | static — built once, and portable |
+| the place (domain, port) | never static; read it from the request |
+| data | render at runtime · a declared snapshot with a digest · generate it as a release step |
+
+The default is **render at runtime**: the build needs no database, and the page
+reads its data where the data lives. Choose a declared snapshot when you need
+static bytes — the build then reads a frozen export whose digest is a declared
+input, not a live database. Choose a release step when the bytes must be
+produced on the way to the deployment; that is the same kind of step as a
+migration, not a new concept.
+
+A build that reads data it has not declared is not hermetic, and the fact is
+invisible: it succeeds on the machine that happens to have the database.
+
+## What it carries
+
+| key | what it says |
+| --- | --- |
+| `schemaVersion` | which format this is; checked before anything else |
+| `kind` | `application` or `library` |
+| `identity` | `slug`, `name`, `version`, `description` per locale |
+| `roles` | each with its own working directory, per-mode argv commands, optional listener and `drainFloorMs` |
+| `build` | the build command and the artifact paths it produces |
+| `requires` | what the code needs and does not provide, per phase (`release`, `start`) |
+| `release` | what must happen once before any role starts — migrations declared as bytes |
+| `env` | the variables a deployment must supply, by name and shape |
+
+Two details are load-bearing:
+
+- **A role may declare no listener at all.** A queue consumer, a bot or a
+  scheduler is a role like any other; readiness belongs to a role rather than to
+  the application.
+- **Migrations are declared as bytes** — `engine`, `root`, `lockfile` — not as a
+  command to run. The side that can see the deployment decides what to do with
+  them: exact contents, admission verdict, whether a preflight can be skipped
+  because nothing touches the database.
+
+## Narrowing it for your project
+
+A project that speaks exactly two locales narrows the shipped schema; it does
+not write its own copy of the rest.
+
+```ts
+import { z } from 'zod';
+import { ProjectDeclarationSchema, parseProjectDeclaration } from 'stitchkit/declaration';
+
+const Narrowed = ProjectDeclarationSchema.safeExtend({
+  identity: ProjectIdentityNarrowedSchema,
+});
+```
+
+`safeExtend` keeps the refinements the shipped schema carries. Extending the
+declaration itself is a breaking change to a published schema and moves the
+minor, with a migration section like any other.
+
+## Related
+
+- [ADR 0104](../decisions/0104-the-project-declaration-ships-from-the-framework.md)
+  — why the schema ships from the framework rather than from each project.
+- [API reference](../api/reference.md#stitchkitdeclaration) — every export.
+
+==============================================================================
+# API reference: `stitchkit/declaration`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/declaration`
+
+Zod-only, dependency-free. The **project declaration**: the single
+machine-readable statement a repository makes about itself, read by the project,
+by the scaffolder that writes the first copy, and by whatever builds a source and
+binds the artifact into a deployment. It ships from the framework so those
+readers cannot hold different copies of the same schema.
+
+`identity` identifies the repository-local buildable source/artifact, not a product project, checkout
+or harness workspace. Product↔repository membership is explicit and many-to-many, owned by an
+external registry; dependency edges do not establish membership. Private companion context is never
+required in this public schema. See [identity boundaries](../guide/declaration.md#identity-is-not-product-membership).
+
+**Declaring yourself is optional.** A project with no `project.json` is a
+complete project: nothing else in the framework imports this entrypoint, no
+build, test or start path looks for a declaration, and its absence is never an
+error or a warning.
+
+The rule the schema exists to hold: **a declaration must be complete and
+meaningful when no machine exists**. A field that cannot be filled in without
+knowing where the code will run is a binding supplied by the deployment, not a
+declaration made by the repository.
+
+**Structure is the guarantee**: nothing here requires a value of the place. A
+command is `executable` plus an `args` array, no part may be an absolute path or
+carry an inline value (`--port=8080` must be `['--port', '8080']`), paths are
+repository-relative, bindings are named by variable and never valued, and a
+listener's variables must exist in `env.variables` with matching shapes.
+
+**Hygiene is the filter**: every remaining free string is checked against
+`namesAMachine` — a scheme, a protocol-relative host, an absolute or
+home-relative path, a Windows drive, a `host:port` pair, a bare IPv4 literal —
+and a number after a port flag is refused. It catches known shapes; it is not a
+secret scanner, and a secret or hostname written as a plain argument passes.
+
+Unknown keys are **refused**, not stripped. A key one reader does not recognise
+is a disagreement between programs that never meet, and discarding it silently
+is how a partially understood declaration becomes a running, wrong deployment.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `ProjectDeclarationSchema` / `ProjectDeclaration` | schema / _type_ | the declaration: `schemaVersion`, `kind`, `identity`, `roles`, `build`, `requires`, `release`, `env` |
+| `parseProjectDeclaration` | function | parse a declaration, refusing an unrecognised `schemaVersion` **before** any field is read |
+| `PROJECT_DECLARATION_SCHEMA_VERSION` | constant | the declaration format this build understands — the number a reader refuses on |
+| `namesAMachine` | function | why a string names a particular machine, or `undefined` — the one predicate every free string is checked against |
+| `findProjectRole` | function | the role with a given name, or `undefined` |
+| `ProjectIdentitySchema` / `ProjectIdentity` | schema / _type_ | `slug`, `name`, `version` and a per-locale `description` |
+| `ProjectRoleSchema` / `ProjectRole` | schema / _type_ | one runnable role: a `workingDirectory` inside the source, per-mode `commands`, an optional `listener`, and `drainFloorMs` |
+| `ProjectCommandSchema` / `ProjectCommand` | schema / _type_ | `executable` plus `args` — argv, never a shell string |
+| `ProjectRoleCommandSchema` / `ProjectRoleCommand` | schema / _type_ | a command run under a supervisor: additionally never a script runner, because a launcher duplicates the shutdown signal |
+| `ProjectListenerSchema` | schema | `portVariable`, `bindVariable` and `readinessPath` — **absent means the role has no listener at all** |
+| `ProjectRunModeSchema` | schema | the run modes a role declares commands for |
+| `ProjectBuildSchema` | schema | build `command`, the set of `artifacts` it produces — more than one path is normal — and any declared data `inputs` |
+| `ProjectBuildInputSchema` / `ProjectBuildInput` | schema / _type_ | data the build may read: a `name`, a frozen export `path` inside the source, and the `sha256:` `digest` that pins its bytes. **Absent `inputs` means the build reads no data** — an answer, not a gap |
+| `ProjectRequirementSchema` / `ProjectRequirementPhaseSchema` | schema | something the code needs but does not provide, and the `phases` — `release`, `start` — it is needed in |
+| `ProjectReleaseSchema` / `ProjectMigrationsSchema` | schema | what must happen once before roles start; migrations are declared as `engine`, `root` and `lockfile` — **bytes, not a command to run** |
+| `ProjectEnvVariableSchema` / `ProjectEnvVariable` / `ProjectEnvShapeSchema` | schema / _type_ | a variable a deployment must supply: `name`, `shape`, `required`, and `members` for an enum |
+| `ProjectSlugSchema` | schema | lowercase hyphen-separated identity everything else is named after |
+| `ProjectDescriptionSchema` | schema | description per locale tag |
+| `RepositoryPathSchema` | schema | a path inside the source — absolute, `..`, `~` and Windows paths are refused |
+| `BindingVariableSchema` | schema | the NAME of an environment variable a deployment fills in |
+
+Version handling is **fail-closed**: an unrecognised `schemaVersion` is refused,
+never assumed compatible, and refused before any field is read so a newer
+declaration reports as a version this build cannot serve rather than as a list of
+unrecognised keys.
+
+To compose a stricter declaration, build on the exported member schemas — for
+example `ProjectDeclarationSchema.safeExtend({ identity: … })`, which keeps the
+boundary refinements in force. `ProjectDescriptionSchema` is a record, so narrow
+it by replacing the field rather than extending it.
+
+---

package/llms/files.txt

@@ -0,0 +1,33 @@
+# stitchkit/files — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/files`  (docs/api/reference.md)
+
+==============================================================================
+# API reference: `stitchkit/files`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/files`
+
+Peer-free Bun/Node filesystem capability. Browser/contract-safe refs are also
+available from `stitchkit/contract`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createManagedFileBoundary` | function | bind an application-owned root, optionally creating one final directory under a trusted existing parent |
+| `ManagedFileBoundary` | _type_ | non-reopenable `read`/`write` capability over canonical relative paths |
+| `ManagedFileBoundaryConfig` | _type_ | bound root, optional `createRoot`, finite read/write/inspection limits, inspector and cleanup observer |
+| `ManagedFileRefSchema` / `ManagedFileRef` | schema / _type_ | transport-safe relative path, measured size and optional media metadata |
+| `ManagedFilePathSchema` / `ManagedFilePath` | schema / _type_ | canonical POSIX relative managed-file path |
+| `ManagedFileSource` | _type_ | bounded immutable bytes plus validated ref passed to upload callbacks |
+| `ManagedFileReadOptions` / `ManagedFileWriteOptions` | _type_ | per-operation byte cap, signal and atomic write policy |
+| `ManagedFileError` / `ManagedFileErrorCode` | class / _type_ | stable boundary failures; registered `FILE_*` mistakes are caller-safe while `FILE_IO_ERROR` remains internal |
+| `ManagedFileInspector` | _type_ | bounded-prefix read/write inspection callback with a finite cancellation signal that cannot own path or size |
+| `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
+| `writeFileAtomic` / `writeFileAtomicSync` / `WriteFileAtomicOptions` | function / _type_ | replace a file atomically: a random staging name created exclusively (never through a planted link), the mode set on the descriptor before the file is visible (default `0o600`, not masked by the umask), `fsync`, rename; a failure leaves the target and no staging file. The asynchronous form keeps the event loop running |
+| `withExclusiveLock` / `ExclusiveLockOptions` / `ExclusiveLock` / `ExclusiveLockOwner` | function / _type_ | run work under an exclusive lock between processes — a file recording its owner (pid, host, machine identity, time); waits up to `timeoutMs` (default 10 s) and stops on `signal`; a dead owner on this machine is taken over, a live, slow or foreign one never is; an ownerless lock only after `ownerlessGraceMs` |
+| `ExclusiveLockError` | class | `LOCK_TIMEOUT` naming the resource and its holder, or `LOCK_ABORTED` with the signal's reason |
+
+---

package/llms/geo.txt

@@ -0,0 +1,114 @@
+# stitchkit/geo — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: Guide: GeoIP  (docs/guide/geo.md) · API reference: `stitchkit/geo`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: GeoIP  (docs/guide/geo.md)
+==============================================================================
+
+---
+title: GeoIP
+description: A server-only managed GeoIP reader with three observable states and last-known-good generation reloads.
+type: guide
+status: active
+created: 2026-09-06
+updated: 2026-09-06
+---
+
+# GeoIP
+
+`stitchkit/geo` is a server-only, evolving entrypoint for reading local GeoIP
+databases without making a database vendor part of the framework contract. It
+exposes a managed resolver, a peer-neutral reader boundary and an optional
+MaxMind adapter.
+
+## MaxMind
+
+Install `maxmind` only in applications that use the adapter:
+
+```bash
+bun add maxmind
+```
+
+Create one resolver and place it in the application resource graph:
+
+```ts
+import { createApplication } from 'stitchkit/application';
+import { createGeoIpResolver, createMaxMindGeoIpLoader } from 'stitchkit/geo';
+
+const geo = createGeoIpResolver({
+  paths: {
+    city: '/srv/geo/GeoLite2-City.mmdb',
+    asn: '/srv/geo/GeoLite2-ASN.mmdb',
+  },
+  loader: createMaxMindGeoIpLoader(),
+  reload: { intervalMs: 60_000 },
+  onError(error) {
+    logger.warn('GeoIP reader unavailable', { error });
+  },
+});
+
+const application = createApplication({ resources: [geo] });
+```
+
+The loader imports the optional peer lazily. City and optional ASN files open
+as one revision: if either changes during the open, the incomplete generation
+is discarded.
+
+## Three states
+
+`geo.snapshot()` distinguishes facts that must not be collapsed:
+
+- `uninitialized` — the managed resource has not started, or has closed;
+- `unavailable` — no usable database generation could be opened;
+- `ready` — lookups use a complete generation.
+
+A refresh failure while a reader is already `ready` preserves that reader and
+sets `reloadError`. This is last-known-good service, not a successful refresh.
+Applications decide whether that fact degrades their own readiness.
+
+## Lookups
+
+```ts
+const attribution = await geo.resolve(requestIp);
+```
+
+`resolve` returns `null` for invalid, loopback, private, link-local and otherwise
+non-public addresses without querying the reader. A database miss or lookup
+failure also returns `null`; `onError` receives operational failures. A result
+may include country, region, city, postal, coordinates, timezone and ASN fields.
+
+When a reload succeeds, new lookups move to the new generation immediately.
+The previous reader closes only after its in-flight lookups finish.
+
+## A custom reader
+
+Use `GeoIpReaderLoader` when the database is not MaxMind-compatible. `revision`
+must identify the complete input generation and return `null` when it cannot be
+read. `open` returns a reader for exactly that revision. Stitchkit serializes
+reloads, swaps generations and owns their close lifecycle.
+
+Download schedules, licenses, database paths, attribution persistence and
+analytics policy belong to the application.
+
+==============================================================================
+# API reference: `stitchkit/geo`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/geo`
+
+Server-only managed GeoIP generations. Applications own database acquisition,
+licensing and domain mapping; the optional MaxMind peer is loaded only when its
+adapter is used.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createGeoIpResolver` / `GeoIpResolver` / `GeoIpResolverOptions` / `GeoIpSnapshot` | function / _type_ | public-IP lookup over one stable reader generation; unavailable start, last-known-good degraded reload and cleanup are explicit states |
+| `createMaxMindGeoIpLoader` / `MaxMindGeoIpLoaderOptions` / `MaxMindGeoIpPaths` | function / _type_ | lazy optional-peer City+ASN loader with stable before/after file revision checks |
+| `GeoIpReader` / `GeoIpReaderLoader` | _type_ | peer-neutral reader/generation seam for adapters and tests |
+| `GeoAttribution` / `mapGeoIpRecord` | _type_ / function | generic optional place and autonomous-system projection; application-specific fields remain outside |
+
+---

package/llms/google.txt

@@ -0,0 +1,27 @@
+# stitchkit/google — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/google`  (docs/api/reference.md)
+
+Also read:
+- see `llms/oauth.txt` for the OAuth & OpenID Connect guide
+
+==============================================================================
+# API reference: `stitchkit/google`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/google`
+
+Server-only Google code exchange and verified OIDC identity. This entry requires the optional
+`google-auth-library` peer. See the [OAuth guide](../guide/oauth.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createGoogleOidcClient` / `GoogleOidcClient` / `GoogleOidcClientConfig` | function / _type_ | exact-redirect, deadline-bounded code exchange and verified identity projection |
+| `ExchangeGoogleAuthorizationCodeInput` / `GoogleOidcIdentity` / `GoogleOidcClaims` | _type_ | callback input, provider-neutral result and verifier seam claims |
+| `GoogleOidcExchangeInput` / `GoogleOidcTokenTransport` / `GoogleOidcIdTokenVerifier` | _type_ | injectable transport and verifier boundaries used by production and deterministic tests |
+| `GoogleOidcError` / `GoogleOidcErrorCode` | class / _type_ | safe `MISCONFIGURED`, `INVALID_CREDENTIAL` or retryable `UPSTREAM_UNAVAILABLE` failure |
+
+---