@jimhoyd/urlcode 0.4.2 → 0.4.6

package/docs/OBSERVABILITY.md

@@ -1,222 +0,0 @@
-# Observability
-
-URLCode reports what it does through three interfaces built on one stream of
-events: the JSON log on stdout, operator **observers** that receive the same
-events in process, and a **metrics snapshot** of counters derived from them,
-optionally served in Prometheus format. Observers mirror [host plugins](PLUGINS.md):
-they are JavaScript an operator passes to `startServer` or `createRuntime`,
-never something a project's YAML can name, and they run with the host's
-privileges. [Monitoring](MONITORING.md) is the operator's guide to probes,
-recipes and alerts; this page is the contract.
-
-```js
-import { startServer } from '@jimhoyd/urlcode';
-
-await startServer({
-  project: './site',
-  observers: [myObserver],   // in-process event and metrics sinks
-  metrics: true,             // GET /_urlcode/metrics, Prometheus text format
-});
-```
-
-## Event catalogue
-
-`events` in `@jimhoyd/urlcode/observability` is a frozen object mapping each event name
-to the complete list of fields it may carry. A test runs a real server and
-holds every record to it, so a field or event that is not in the table below
-does not ship. Fields marked *optional* are present only in the situations
-named.
-
-| Event | Fields | Emitted when |
-|---|---|---|
-| `request` | `requestId` string, `status` integer, `durationMs` number; `method` string and `route` string or `null` with `--request-log detailed` | Every response the server wrote, including probes and shed 503s. `route` is the configured pattern (`/u/{id}`) or the probe path, never the requested path. |
-| `reload` | `status` `ok`/`rejected`; `version` string and `routes` integer on `ok` | `app.reload()` or the development watcher swapped, or refused to swap, the snapshot. |
-| `watch` | `status` `failed` | The development watcher could not fingerprint the project. |
-| `function_worker` | `status` `started`/`restarting`, `slot` integer; `attempt` and `delayMs` integers on `restarting` | A function worker became ready or is scheduled for replacement. |
-| `signal` | `outcome` (`accepted`, `delivered`, `failed`, `dropped`), positive `count` | Best-effort webhook totals; no destination, request data or secrets. |
-| `logs_dropped` | `count` integer | The JSON logger shed records because stdout was not writable. Written by the logger itself, so observers do not see it. |
-| `observer` | `status` `failed`, `name` string | An observer hook threw or rejected. Written to the default log only, never to observers. |
-| `throttle` | `route`, `outcome` `allowed`/`exceeded`, `remaining` integer | A throttle decision. `allowed` is logged only in `mode: report`; enforce mode logs refusals. |
-| `agents` | `route`, `list` string, `outcome` `denied`/`reported` | A User-Agent matched a list. The list name is logged, never the header. |
-| `cache` | `route`, `outcome` `hit`/`stale`/`miss`/`store` | A cache lookup or store. |
-| `listening` | `address`, `port`, `mode`, `origin` | Printed once by the CLI at startup, not emitted by the server. |
-
-Every event carries `event` (its name). Numbers are JSON numbers, never
-strings.
-
-### Privacy guarantees
-
-No event, snapshot or exposition carries a request URL, path, query string,
-header, body, client address, User-Agent string, binding, secret or user
-exception text. `route` is always a configured pattern
-from reviewed YAML. `requestId` is server-generated unless
-`--trust-request-id` accepts one from a trusted proxy. An observer
-that logs should keep the same rule; nothing in an event lets it break it.
-
-## Observers
-
-```js
-const myObserver = {
-  name: 'forwarder',            // ^[a-z][a-z0-9-]{0,63}$, unique per server
-  version: '1.0.0',             // any string up to 64 characters
-  onEvent(event) {},            // every record the JSON logger writes, in order
-  onMetrics(snapshot) {},       // the metrics snapshot, on the interval and at close
-  async onClose() {},           // release resources; reverse order
-};
-```
-
-In TypeScript the contract is `Observer` from `@jimhoyd/urlcode/observability` (also
-exported from `urlcode`), with `ObserverEvent` for a record and
-`MetricsSnapshot` for what `onMetrics` receives; the declarations ship with the
-package:
-
-```ts
-import type { Observer, ObserverEvent, MetricsSnapshot } from '@jimhoyd/urlcode/observability';
-
-const myObserver: Observer = {
-  name: 'forwarder',
-  version: '1.0.0',
-  onEvent(event: ObserverEvent) { queue.push(event); },
-  onMetrics(snapshot: MetricsSnapshot) { gauge.set(snapshot.requests.inFlight); },
-};
-```
-
-Validation (`validateObservers`) matches plugins: at most 32 observers, each
-an object with a kebab-case `name` no other observer uses, a `version` string,
-every declared hook a function and at least one present. It runs before the
-listener starts, so a bad observer fails startup rather than a request.
-
-`onEvent` receives the same object the logger serialised, after the logger,
-observers in array order. Do not mutate it. It runs on the request path, so
-keep it cheap: buffer and flush on a timer rather than awaiting a network
-call. A hook that throws or returns a rejecting promise is isolated: the
-request is unaffected, the next observer still runs, `observers.errors` in
-the snapshot increments and one `observer` record goes to the default log.
-Nothing is retried; an observer that needs delivery guarantees owns its own
-queue.
-
-`onMetrics` receives a fresh snapshot every `metricsIntervalMs`
-(`startServer` option, `0` off by default, 1 s to 1 h) and once at `close()`.
-`onClose` runs in reverse order after the runtime has closed.
-`app.observers` lists the `{ name, version }` pairs.
-
-`createRuntime(project, { observers })` takes the same array for embedding
-without the server: the runtime's own sink and counters are then yours, and
-`runtime.metrics()` returns its snapshot. `startServer` never passes its
-observers down to the runtimes it creates, so a reload does not re-register
-them and counters survive reloads.
-
-`createObserverSink(observers, fallbackLog)` is the fan-out itself, exported
-for tests and custom hosts: it returns a `log(event)` function with `.metrics`,
-`.publish(snapshot)` and `.close()`.
-
-## Metrics snapshot
-
-`app.metrics()` and `runtime.metrics()` return a plain object, safe to
-`JSON.stringify`, of counters since the process started serving. Numbers
-only; the one keyed table is `requests.byRoute`, keyed by configured pattern
-and capped at 10 000 keys.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `version` | gauge | Snapshot shape version, currently `2`. |
-| `uptimeSeconds`, `rssBytes` | gauge | Process facts. |
-| `requests.total`, `requests.byStatusClass.{2xx,3xx,4xx,5xx}` | counter | Application responses, including shed 503s. |
-| `requests.inFlight` | gauge | Requests holding application admission now. |
-| `requests.byRoute[pattern]` | counter | Responses per matched route. A shed or unmatched request has no route. |
-| `health.total`, `health.byStatusClass`, `health.inFlight` | counter, gauge | The probe budget: `/_urlcode/health`, `/_urlcode/ready` and `/_urlcode/metrics`. |
-| `shed.requests`, `shed.health` | counter | 503s answered because an admission budget was full. |
-| `reloads.ok`, `reloads.rejected` | counter | Snapshot swaps. |
-| `watch.failed` | counter | Development watcher failures. |
-| `functionWorkers.started`, `functionWorkers.restarts` | counter | Worker starts and scheduled replacements. |
-| `functionWorkers.healthySlots`, `functionWorkers.slots` | gauge | Ready slots and configured slots of the serving runtime. |
-| `policies.throttle.{allowed,exceeded}` | counter | Throttle decisions (see the catalogue for what enforce mode logs). |
-| `policies.agents.{denied,reported}` | counter | Agents decisions. |
-| `policies.cache.{hit,stale,miss,store}` | counter | Cache outcomes. |
-| `signals.{accepted,delivered,failed,dropped}` | counter | Best-effort webhook outcomes; exposed as `signals_total` with outcome labels. |
-| `logsDropped` | counter | Records the JSON logger shed. |
-| `observers.errors` | counter | Observer hooks that threw or rejected. |
-
-Policy counters are derived from the `throttle`, `agents` and `cache` events
-as they pass through the sink, so the policies themselves have no metrics
-code. Runtime facts that never become events (admission, shedding, slot
-health) are recorded by the server directly. Counters are per process;
-aggregation across replicas is the scraper's job.
-
-## Prometheus exposition
-
-`startServer({ metrics: true })`, or `urlcode serve --metrics` on the command
-line, serves `GET /_urlcode/metrics` as `text/plain; version=0.0.4`, rendered from the same snapshot by
-`renderPrometheus(snapshot)`, a pure function you can also call yourself.
-Every metric is prefixed `urlcode_`; counters end in `_total`; the only labels
-are `status_class`, `route` and `outcome`.
-
-```
-# HELP urlcode_requests_total Application requests answered since start, by status class.
-# TYPE urlcode_requests_total counter
-urlcode_requests_total{status_class="2xx"} 1042
-urlcode_route_requests_total{route="/u/{id}"} 977
-urlcode_requests_in_flight 3
-urlcode_shed_total{outcome="requests"} 0
-urlcode_reloads_total{outcome="ok"} 2
-urlcode_function_worker_restarts_total 0
-urlcode_function_worker_healthy_slots 2
-urlcode_throttle_total{outcome="exceeded"} 14
-urlcode_cache_total{outcome="hit"} 511
-urlcode_logs_dropped_total 0
-urlcode_observer_errors_total 0
-urlcode_uptime_seconds 86400
-urlcode_process_rss_bytes 71303168
-```
-
-The endpoint is **off by default**. It shares the probes' admission budget
-(`--max-in-flight-health`) and the same bind host, which is `127.0.0.1`
-unless `--host` says otherwise. Like the probes it is unauthenticated and
-discloses route patterns and traffic shape, so **do not expose it publicly**:
-keep it on an internal interface or restrict it at the ingress. A scrape
-counts under `health`, not under application requests. See
-[`examples/monitoring/prometheus-scrape.yaml`](../examples/monitoring/prometheus-scrape.yaml).
-
-## OpenTelemetry sketch
-
-The runtime has no OpenTelemetry dependency. An observer can forward events
-to an OTLP exporter and map the snapshot onto instruments; this is a sketch,
-not shipped code, and omits batching, resource attributes and error handling.
-
-```js
-// Sketch. `logs` and `meter` come from the OpenTelemetry SDK the operator
-// configures; the runtime knows nothing about them.
-export function otelObserver({ logger, meter }) {
-  const requests = meter.createCounter('urlcode.requests', { unit: '{request}' });
-  const inFlight = meter.createObservableGauge('urlcode.requests.in_flight');
-  let last;
-  inFlight.addCallback(result => { if (last) result.observe(last.requests.inFlight); });
-  return {
-    name: 'otel', version: '0.1.0',
-    onEvent(event) {
-      // Every field is already safe to attach as an attribute.
-      logger.emit({ body: event.event, attributes: event });
-      if (event.event === 'request') requests.add(1, { status_class: `${Math.floor(event.status / 100)}xx`, route: event.route ?? '' });
-    },
-    onMetrics(snapshot) { last = snapshot; },   // the gauge reads the latest snapshot
-  };
-}
-```
-
-Counters in the snapshot are cumulative, so they map to OpenTelemetry
-`Counter` instruments read through an observable callback, or to a
-Prometheus receiver scraping `/_urlcode/metrics` directly. `durationMs` on
-`request` is the input for a `Histogram`; the runtime does not bucket it.
-
-## What is not provided
-
-- **Tracing.** There are no spans and no context propagation; `requestId` is
-  the only correlation key, and a trusted proxy can supply it.
-- **Sampling.** Every event is delivered to every observer, or shed by the
-  logger under back-pressure and reported as `logs_dropped`.
-- **Persistence and aggregation.** Counters live in process memory, reset on
-  restart, and describe one process. Retention and cross-replica sums belong
-  to the collector.
-- **Per-URL analytics.** By design; see the privacy guarantees.
-- **Adapters.** Vercel, Lambda and Cloudflare handlers emit through the
-  platform's own logging and do not take observers.

package/docs/OPEN-DECISIONS.md

@@ -1,149 +0,0 @@
-# Decisions to align
-
-Last reconciled 2026-09-20 against open and closed issues (#242); the source
-review it began from is dated 2026-09-19 (core `db375bf`, now archived).
-This is the maintainer's decision list, not a second implementation backlog.
-The [roadmap](../ROADMAP.md) gives sequence and the [archive](archive/README.md)
-keeps earlier discussions. Recommendations below are not accepted decisions.
-
-## Principles already settled, in plain language
-
-- **Describe first, code only when needed.** Use a supported YAML feature or
-  extension before writing plumbing. Custom application code is still welcome.
-- **Your application code runs like normal Node code.** Functions and middleware
-  are trusted by default. `sandbox: true` deliberately restricts a route's whole
-  function/middleware chain. Request data still needs validation in either mode.
-- **A grant controls what URLCode supplies, not what trusted code can access.**
-  Trusted code can independently read the host environment, files and network.
-  Opt-in sandboxing retains its existing isolation and revision-pinned grants.
-- **Portable does not mean every host supports every feature.** Keep infrastructure
-  out of route YAML and reject unsupported targets before activation.
-- **Core works alone; optional packages add accounts, admin and presentation.**
-  Core never imports those implementations. Shared UI belongs in `urlcode-ui`.
-- **Documentation stays beside the owning code.** Core guides live here;
-  extension contracts and implementation status live in their repositories.
-  `urlcode-docs` is deleted. `urlcode-short` and `urlcode-dynamic-link` are retired.
-- **Passing tests proves the tested behavior.** It does not prove deployment,
-  accessibility, hostile tenant isolation or independent security assessment.
-- **Keep the free runtime useful.** Apache-2.0 remains unchanged; no mandatory
-  hosted account, paid capability gate or provider lock-in belongs in core.
-
-## Decisions still needed
-
-| Decision | What the code says today | Recommendation and consequence |
-|---|---|---|
-| Where does work status live? | Several old plans repeated issues and continued calling delivered work unfinished. | Issues for actionable status, this short roadmap for sequence, archive for completed proposals. Preserve evidence gaps when archiving. |
-| Expand into business applications now? | No collection handler or proposed business suite is implemented; the model-backed benchmark evidence is missing. | Measure existing tasks and record repeated application plumbing before selecting a collection/CMS/forms project. Retired short-link products stay retired. [Proposal](SPIKE-BUSINESS-SUITE.md). |
-| Fold extension schemas into retrieved context? ([#174](https://github.com/jimhoyd-com/urlcode/issues/174), open) | `urlcode extensions` and the MCP `get_extensions` query return the registered configuration and policy schemas, but `src/context.ts:113` reports `extensions` as names only, so an author writing `extensions.<name>.config` or `policies.extensions.<name>` must run the separate operator-authorized query first. | Decide from retrieval and task evidence, not preference: the existing small-task harness can measure whether folding schemas into bounded context improves authoring. Keep the token budget bounded and never auto-load a project-selected host file. This is a discovery improvement, not a defect in the existing query. |
-| Build the tested-image promotion path? ([#233](https://github.com/jimhoyd-com/urlcode/issues/233), open) | [Design and an inert invariant helper](CONTAINER-PROMOTION.md) are merged. `release.yml` still rebuilds from source when `PUBLISH_CONTAINER` is true, and a retry accepts an existing `:VERSION` on its `revision` label alone. Live GHCR state and whether GHCR preserves an OCI digest through `skopeo`/`crane` are unverified. | The reason is integrity (tested bytes are the shipped bytes), not speed: CI's image build took about 12 seconds, so a cross-run build cache is not justified and should not be added. Recommendation: do not implement while publication is off and GHCR is uninspected. First grant `read:packages` and inspect historical labels and digests; then land a candidate-side image build behind an operator input, inspect one real candidate, and only then change the publisher. Not changed here. |
-| Keep the POST-plus-`request.body` sandbox advisory? | `src/readiness.ts` nudges any code-running route that accepts POST with a declared `request.body` and declares neither `sandbox: true` nor `sandboxReason`. It is advisory only: never fails `audit`, never changes `ready`. | The nudge keys on request *shape* while [AI authoring](AI-AUTHORING.md) tells authors to decide on *code* trust, so it can read as "untrusted input implies sandbox" -- the reasoning that guidance explicitly rejects. It still has value as a prompt to record a decision. Recommendation: keep the trigger, restate the message as a request to record the trust decision (`sandbox: true` or `sandboxReason`) rather than as a suggestion that this route may need isolation. Not changed here; #196 was a docs/tooling alignment pass. |
-
-The broader [AI benchmark proposal](SPIKE-AI-FRAMEWORK-BENCHMARK.md) also needs a
-chosen application, model-run budget and execution authorization. The existing
-small-task harness can supply evidence without committing to that larger study.
-
-## Accepted: one Node deployment per project
-
-**Decided 2026-09-19.** Projects that use `function` or `middleware` deploy as
-**one trusted Node process** — a container or a VM running the project as it
-runs locally. That is the supported execution model, and it needs no new work:
-it is what the runtime already does.
-
-**Per-route Lambda compilation is not pursued.** The alternative on the table
-was a build step emitting one Lambda per `function` route
-([the proposal](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md)). It is declined for now, on three
-grounds the proposal itself states:
-
-1. It would replace the sandbox guarantee rather than preserve it, and lose the
-   fresh-per-invocation state that `sandbox: true` currently guarantees.
-2. It would make this project the author of generated IAM roles — a
-   security-critical output it has never owned.
-3. It would trade an honest refusal for a larger claim nobody has deployed.
-
-Against that, a single Node deployment supports every route type today with no
-compiler, no generated infrastructure and no second isolation story to document.
-
-**What follows from this decision:**
-
-- AWS and Vercel continue to refuse `function` and `middleware` at activation,
-  naming the route (`src/capabilities.ts`, `activateNativeOnly` in
-  `src/adapters.ts`). That refusal is now a **deliberate position**, not a gap
-  awaiting an adapter. Documentation should say so rather than implying the
-  support is coming.
-- Serverless targets remain first-class for the declarative route types they can
-  actually serve; nothing about static or native-only deployment changes.
-- [SPIKE-LAMBDA-COMPILE.md](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md) is kept as the analysis
-  behind this decision, not as a plan. Reopen it only on evidence of real demand
-  for URLCode `function` routes specifically on AWS serverless — the proposal's
-  own §6 already scopes what a first attempt would be.
-
-This decision is about the *execution model*, not about AWS. Deploying the Node
-process to AWS (ECS, EC2, App Runner) is an operator choice this fully supports.
-
-## Accepted: per-package release tags
-
-**Decided 2026-09-19.** Workspace packages under `packages/` release on
-Changesets' own `<package name>@<version>` form — for example
-`@jimhoyd/urlcode-ui@0.1.0-alpha.6`. Core keeps bare `v*`.
-
-**The problem.** Core and all three extensions arrived here triggering on
-`tags: ['v*']`, and their alpha tags overlap outright: ui shipped
-`v0.1.0-alpha.2` through `-alpha.5`, admin `v0.1.0-alpha.1` and `-alpha.3`,
-auth `v0.1.0-alpha.1` through `-alpha.3`. Across four repositories that was
-fine. In one repository a single bare tag push starts more than one release
-workflow. Each one fails closed on its own tag-matches-manifest check, so
-nothing can mis-publish — but "two workflows race and one errors on every
-release" is not a release process, and the failure is confusing rather than
-informative.
-
-**Why Changesets' form rather than a prefix like `ui-v0.1.0-alpha.6`.** Both
-work and both are valid ref names. The deciding factor is that Changesets is
-already the chosen release flow, and `changeset tag` emits the
-`<name>@<version>` form natively. Picking anything else means writing and
-maintaining a translation layer between the tool that computes the version and
-the tag that triggers the publish — new code whose only job is to disagree
-with a default. The spike chose Changesets partly because it is "cheap and
-low-risk for an agent or a human to generate correctly"; hand-rolling the tag
-shape undercuts exactly that.
-
-**Why the two schemes cannot collide.** A scoped package name begins with `@`,
-and GitHub's `v*` filter requires a leading `v`, so no tag can match both.
-Verified rather than assumed, including that `*` does not match `/` in a filter
-pattern, so `@jimhoyd/urlcode-ui@*` matches the version segment only.
-
-**Core's asymmetry is forced, not preferred.** Under layout A core is the
-repository root rather than a workspace member, so Changesets does not manage
-it and `changeset version` will not bump it. Core therefore keeps the tag
-scheme and release workflow it already had.
-
-[`scripts/check-release-tags.ts`](../scripts/check-release-tags.ts) enforces
-this in `npm run check`: it rejects a workspace package workflow that does not
-trigger on its own `<name>@*`, rejects any workflow other than core's claiming
-`v*`, and independently asserts that no two filters can match the same tag. The
-reasoning above is the kind of prose that rots as soon as `auth` and `admin`
-arrive, which is the whole argument this repository makes for enforcing checks
-over documented intent.
-
-## Completed work (archived)
-
-Closed questions, the completed monorepo migration (ui, auth and admin are
-workspace packages; released from this repository) and the 2026-09-19 source
-review baseline live in
-[archive/2026-09-20/OPEN-DECISIONS-COMPLETED.md](archive/2026-09-20/OPEN-DECISIONS-COMPLETED.md).
-The migration plan is [archived](archive/2026-09-19/SPIKE-MONOREPO.md). Versions
-and channels are in [version alignment](VERSION-ALIGNMENT.md) and
-`npm run release:status`, not here.
-
-## Accepted: middleware withdrawn rather than consolidated
-
-**Decided 2026-09-19.** `@jimhoyd/urlcode-middleware` was unpublished and its
-repository deleted; there is no `packages/middleware` and nothing to fold into
-core afterward (#172, closed as moot). Per-route middleware is native to core
-via the `middleware:` array ([MIDDLEWARE.md](MIDDLEWARE.md)). The generic
-extension wrapping hook (`ExtensionInstance.middleware`,
-`RuntimeExtension.cacheSensitive`) stays in core's contract for other extensions
-but is no longer exercised by any shipped package, so do not assume it is
-covered. Static targets keep rejecting request-time middleware. The earlier
-instruction to move middleware into the monorepo first was overtaken; its full
-text is retained in the archived record.
-

package/docs/OPERATIONAL-PROOF.md

@@ -1,41 +0,0 @@
-# Operational evidence and deployment acceptance
-
-`node scripts/operational-drills.ts` creates and deletes its own temporary
-project. It runs mixed real HTTP requests against native redirects and
-`function` routes; asserts responses; rejects a bad reload; and activates and
-rolls back a configuration. `URLCODE_SOAK_SECONDS=60` selects a longer run
-(1–3600 seconds, default 5). Output is JSON with request count, batch p99
-duration and RSS. Batch latency is not per-request p99 or a capacity promise.
-CI's `verify` job runs the short drill across a 3-Node (22/24/26) × 3-OS
-(Linux/macOS/Windows) matrix, nine combinations, but only on a push to `main`.
-A pull request runs the same drill across all three Node versions on Linux
-only (3 of the 9 combinations); the macOS/Windows legs only run once a PR
-merges, per `.github/workflows/ci.yml`'s matrix.
-
-Core has no durable store of its own, so this drill has no backup/restore or
-disk-exhaustion exercise: an extension package owning durable state is
-responsible for its own persistence proof. No such package ships today — the
-`urlcode-dynamic-link` package that did has been retired.
-
-## Required proof on the intended deployment
-
-Local/CI passes do not close these gates. `urlcode verify-deployment --target`
-([deployment checks](DEPLOYMENT-CHECKS.md)) records that the deployed responses
-match the project and is the first step of the rollback drill below, not a
-substitute for it. The deployment owner must record:
-
-| Exercise | Acceptance evidence |
-|---|---|
-| Soak | At least 24 hours at expected peak and burst load through actual TLS/ingress; native/function mix, slow clients, response correctness, p50/p95/p99, throughput, error/rejection rate, RSS plateau, CPU and FD growth. Define numerical SLOs before starting |
-| Kill/restart | Kill the server with outstanding requests. Reconcile uncertain mutations by request ID, restore readiness, and prove no duplicate side effects from application code |
-| Rollback | Deploy candidate by exact digest beside last-good, run route assertions, switch ingress, drain, then switch back. Verify configuration/policy compatibility |
-| Monitoring | Deliver test alerts for missing logs, sustained errors, pool rejection/failure, low disk, restart storms and failed readiness to a named on-call owner |
-
-If your deployment adds a durable-state extension, add that extension's own
-backup/restore, logical export/import and disk/log exhaustion exercises to
-this table; core's proof above does not cover them.
-
-Record date, operator, source/app/policy/image digests, topology, hardware/limits,
-commands, duration, synthetic dataset size, raw metrics/log locations, result
-and unresolved findings. A reviewer signs the acceptance record; a blank
-record is not a pass.

package/docs/OPERATIONS.md

@@ -1,201 +0,0 @@
-# Running URLCode yourself
-
-This is the stable 0.1 self-hosted runtime. Its deliberately bounded feature set
-is not a claim of suitability for every production workload. Deploy only workloads
-whose requirements fit the [implemented contract](SPECIFICATION.md).
-Provider adapters, automatic TLS/DNS management, distributed rate limits,
-metrics exporters and durable event delivery are not included.
-
-## Process deployment
-
-Install a reviewed URLCode commit with Node 22.13+ and `npm ci --omit=dev`.
-Keep the runtime separate from an application checkout pinned to its own commit.
-Functions support only relative project JavaScript modules; do not install or
-execute an untrusted application’s package scripts as part of serving it. Validate using
-the same injected environment as the serving process:
-
-```sh
-node /opt/urlcode/dist/cli.js validate --project /srv/my-links
-node /opt/urlcode/dist/cli.js serve --project /srv/my-links \
-  --host 127.0.0.1 --port 3000 --origin https://links.example.com
-```
-
-`--origin` defines the public URL seen by functions; proxy Host/X-Forwarded-*
-headers are intentionally not trusted. Use a process supervisor that restarts on
-failure and sends SIGTERM for shutdown. Shutdown stops accepting requests, gives
-HTTP connections up to 10 seconds, and drains bounded in-flight functions.
-
-Serve a read-only application tree where practical. The operator-owned runtime
-account must be able to read application files/dependencies. Authoring happens
-in development/CI, not by modifying a running replica's filesystem.
-
-## Container deployment
-
-The supplied image packages the runtime; it does not copy your application or
-local secret files. Build from the reviewed runtime checkout:
-
-```sh
-docker build -t urlcode:0.3.0 .
-docker run --rm --name my-links \
-  --read-only --cap-drop ALL --security-opt no-new-privileges \
-  --memory 512m --cpus 1 --pids-limit 128 \
-  -p 127.0.0.1:3000:3000 \
-  -v "$PWD/starters/default:/project:ro" \
-  urlcode:0.3.0
-```
-
-Replace the example mount with your app. The image uses the unprivileged `node`
-user; ensure mounted config/functions are readable by it. Core has no writable
-mount of its own; a future mount-based extension (like `auth`/`admin`, see
-[extensions](EXTENSIONS.md)) is the place for operator-owned writable state.
-Sandboxed application functions cannot access mounted files or installed
-Node packages. The resource values above illustrate
-container limits, not a sizing recommendation; large configuration compilation
-can need more memory. Measure your workload. Tag/redeploy immutable image digests
-in real operation rather than treating a mutable tag as a rollback identity.
-
-## Domains, HTTPS and exposure
-
-Point your domain's DNS at the reverse proxy/load balancer you operate, terminate
-HTTPS there, and forward to the loopback/private URLCode port. Use a tested proxy
-such as your existing Caddy/nginx/load-balancer setup for certificates, connection
-limits and rate limiting. No certificate automation is supplied by URLCode yet.
-Keep direct backend access private. Restrict `/_urlcode/*` endpoints to operators
-at the proxy; they are unauthenticated and reveal route count/config digest.
-
-If functions perform sensitive actions, implement authentication and authorization
-in the application. A short URL is not automatically an access-control mechanism.
-Functions and middleware run trusted and unsandboxed by default, in the host
-process with full Node, filesystem and network access; a route that declares
-`sandbox: true` runs isolated in QuickJS/WebAssembly instead (see
-[function security](FUNCTION-SECURITY.md)). Keep separate deployment
-processes/containers and narrowly scoped credentials as additional boundaries.
-Do not expose a public code-upload/multi-tenant service on the basis of the self-hosted release alone
-without separate security review and stronger service-level containment.
-
-## Secrets and rotation
-
-`dev`, `test`, `routes`, `audit`, `benchmark` and `validate --local` read
-`.env.local`. Authoring and
-permissions inspection do not read credentials or execute functions. `serve` and
-ordinary `validate` use process environment only. Resolve logical names from
-your own secret store/supervisor and inject them at startup; direct provider
-secret-store integrations remain future work. Bindings also require an external,
-revision-pinned operator policy; see [setup](FUNCTION-SECURITY.md). Do not place secret values in
-command-line arguments, route YAML, image layers or Git.
-
-Check tracked files as well as ignore rules. Docker builds use an explicit
-allowlist; npm artifacts include runtime/schema/starter/docs files only. Do not
-build an application image by blindly copying its entire development directory.
-Rotate a credential by replacing its injected value and restarting/redeploying;
-production does not watch or refresh secret values automatically.
-
-## Health, logs and limits
-
-- `GET /_urlcode/health`: process liveness.
-- `GET /_urlcode/ready`: 200 when the active snapshot and all function workers
-  are available; 503 while a worker
-  is unavailable. Busy workers alone do not
-  mark readiness down. A failed worker is replaced with
-  exponential backoff (250 ms doubling to a 30-second ceiling) and readiness
-  reports 503 until every slot is serving again. Replacement does not stop, so a
-  request-triggered deadline cannot disable functions until an operator restarts;
-  a cause that keeps recurring keeps the instance shedding load and needs an
-  operator. Alert on sustained `function_worker` restart events.
-- Probes are answered from their own admission budget (16 by default,
-  `--max-in-flight-health`), so they stay available while the application is
-  saturated without being an unmetered endpoint. They are unauthenticated and
-  report the configuration digest and route count: keep them on an internal
-  interface or restrict them at the ingress.
-- Request logs: JSON request ID, status and duration. No URLs, query strings,
-  headers, bodies, bindings or user exception text. `--request-log detailed` adds
-  the request method and the matched route pattern (`/u/{id}`, or `null` when
-  nothing matched). Both come from the reviewed configuration, never from
-  request-supplied path, parameter or query text, which is what makes per-route
-  error rates and latency available without logging user data.
-- Request IDs are generated per request and returned in `x-request-id`. An
-  inbound `x-request-id` is ignored unless `--trust-request-id` is set, which is
-  only correct when a trusted proxy sets the header and strips client-supplied
-  copies; untrusted values are still rejected unless they are a single header of
-  at most 128 characters from `[A-Za-z0-9_.:-]`. Forward stdout to your log
-  system and alert on sustained 5xx and latency. The default logger drops records
-  when stdout buffering reaches 1 MiB and reports the dropped count when output
-  recovers; alert on `logs_dropped`. Function console output is
-  suppressed; app-specific diagnostics are not yet a first-class feature.
-  Synchronous and asynchronous sink failures are contained; a failed sink drops
-  subsequent output and needs operator recovery. Collectors own rotation/retention.
-- HTTP: 8,192-character target, 16 KiB headers, 1 MiB buffered body, 15-second request
-  receipt timeout, 10-second header timeout, 5-second keep-alive, 1,000 requests
-  per socket and 1,024 active connections. At most 64 application requests are
-  admitted through response completion; excess requests receive 503. Health probes
-  remain available under admission saturation. A 15-second socket inactivity
-  timeout closes stalled readers/writers. Proxy timeouts/rate limits still matter.
-- Functions: a `sandbox: true` route gets 2 concurrent workers (`--workers`),
-  no queue and a 5-second deadline (`--function-timeout-ms`); a trusted route
-  (`sandbox` false or absent, the default) shares the in-flight admission cap
-  instead of a worker pool and races the same deadline. Either mode buffers
-  1 MiB of response (`--max-response-bytes`) and 16 KiB response headers.
-  Saturation 503; timeout 504; error 502.
-  QuickJS guests have a 32 MiB heap and 512 KiB stack budget and no network or
-  host capabilities; a trusted route has neither budget and full Node access.
-  Outer workers have additional V8 limits. Total process/WASM
-  memory still needs deployment-level limits; do not equate guest budget with RSS.
-
-`urlcode serve`/`dev` and the JavaScript server API both configure workers,
-deadlines and byte limits: `--workers`, `--function-timeout-ms`,
-`--max-response-bytes`, `--max-body-bytes`, `--max-in-flight` and
-`--max-in-flight-health`. Set them on the container command line; these are
-deployment controls, not portable route behavior. Horizontal replicas
-must use identical application/config versions and secret bindings. In-memory
-function state is reset after every invocation, not durable/shared application state.
-General application storage needs a future explicit capability broker; no
-storage/network access is exposed to the guest. Core no longer has a native
-link store, and the `urlcode-dynamic-link` extension package that replaced it
-has been retired and unpublished.
-
-The health version combines route-definition and asset-representation digests;
-it does not identify the complete function/runtime release. Record runtime commit,
-application commit, dependency locks and image digest in your deployment system.
-
-## Deployment and rollback procedure
-
-1. Build a candidate from pinned runtime/application revisions and lockfiles.
-2. Validate its config/bindings and run local HTTP tests without external redirects.
-3. Start it on an alternate private port/container. Check readiness and representative
-   redirect/function behavior through the intended proxy configuration:
-   `urlcode verify-deployment --project . --target https://candidate.host` compares
-   version, fixtures, policy headers and site files with the project
-   ([deployment checks](DEPLOYMENT-CHECKS.md)).
-4. Switch proxy traffic after checks pass. Drain the previous instance before stopping.
-5. If checks or observed behavior fail, route traffic back to the retained previous
-   instance/image and its compatible secret bindings.
-
-This is an operator procedure, not an implemented deployment control plane.
-Rollback cannot undo a function's external side effects or migrate an app's
-state automatically. Plan those independently. Keep Git definitions backed up;
-back up any app-owned persistent state separately. YAML routes require no database.
-
-## Capacity and incident planning
-
-See [capacity and concurrency](CAPACITY.md) for hard limits, worker occupancy,
-no-queue rejection, memory/reload budgets and theoretical sizing. See
-[DDoS and recovery](RESILIENCE.md) for ingress responsibilities, incident response,
-rollback/restore procedures, recovery objectives and drills.
-
-See the [release-readiness register](RELEASE-READINESS.md) for evidence and open gates.
-
-## Remaining production validation
-
-Before approving a production deployment: run sustained soak/load tests on its
-hardware, obtain independent security review, exercise failure/restart and
-upgrade/rollback, establish a clear support/reporting policy, and add the needed
-operational metrics. Provider adapters remain separate roadmap work. See
-[roadmap](../ROADMAP.md). No claim of high
-availability, zero downtime or provider portability beyond the Node process
-adapter is made by the current release.
-
-## Security review
-
-The [2026-09-16 internal audit](SECURITY-AUDIT.md) records fixes, regression evidence
-and remaining security/operational gates. This is not an independent assessment.
-