@jimhoyd/urlcode 0.4.1 → 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,224 +0,0 @@
-# Decisions to align
-
-Reviewed 2026-09-19 against core `db375bf` and the current public package sources.
-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? | `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. |
-| 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.
-
-## Closed questions removed from the active list
-
-- Publishing convention is recorded in [version alignment](VERSION-ALIGNMENT.md):
-  publishable manifests on main, releases through reviewed tags/workflows.
-- Core `0.4.0-alpha.2` and current extension releases exist; publishing that
-  already-shipped version is not a next step.
-- Auth/admin kit adoption and shared form helpers are implemented in their code.
-- The UI primitive fallback is retired, which settles the question this table
-  carried. Auth and admin now render every screen through the kit and refuse
-  activation without it (`packages/auth/src/auth.ts`: "there is no
-  shared-primitive fallback"), so "keep both" no longer describes the code.
-- The template pins `0.4.0-alpha.2`. Its skill differences were read against that
-  pin: omitted handlers and advice about the removed management API are stale,
-  not intentional older-version behavior.
-- The guidance checks run through `npm run check` inside `verify`; a regex check
-  is not a schema validator for every example. Extending its coverage is tracked
-  separately, not a reason to weaken review or bypass required checks.
-
-## 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.
-
-## Done: the monorepo migration is complete
-
-**Closed 2026-09-19.** `urlcode-ui`, `urlcode-auth` and `urlcode-admin` are
-workspace packages under `packages/`, and all three have been released from
-this repository — `@jimhoyd/urlcode-ui@0.1.0-alpha.6`,
-`@jimhoyd/urlcode-auth@0.1.0-alpha.6`, `@jimhoyd/urlcode-admin@0.1.0-alpha.4`,
-each on `alpha` with `latest` deliberately held behind. Core's dist-tags are
-unchanged. The three source repositories are gone; their history survives only
-as verified `git bundle`s, because the repository allows squash merges only and
-the imported commits did not survive onto `main`.
-
-The operational runbook is [DEVELOPMENT-PIPELINE.md](DEVELOPMENT-PIPELINE.md)
-and [RELEASE-SECURITY.md](RELEASE-SECURITY.md). The plan itself is archived at
-[archive/2026-09-19/SPIKE-MONOREPO.md](archive/2026-09-19/SPIKE-MONOREPO.md),
-whose closing note records what the plan got wrong — chiefly that its
-strongest argument, the reach of the enforcing checks, only became true after
-both checkers were changed to discover workspace packages.
-
-The section below is kept for the middleware decision it records, which is
-still the reason there is no `packages/middleware`.
-
-## Accepted: monorepo first — middleware withdrawn rather than consolidated
-
-The maintainer confirmed that monorepo work is starting now. The earlier
-recommendation to keep repositories separate for now is superseded.
-
-**Reversed 2026-09-19: the middleware half of this decision no longer applies.**
-This section used to say "move middleware into the monorepo as its own package
-first, preserving its existing API and behavior," and explicitly: "do not
-unpublish or retire the middleware package as part of the initial move."
-That instruction was overtaken. `@jimhoyd/urlcode-middleware` has been
-**unpublished** from npm at `0.1.0-alpha.2` and `jimhoyd-com/urlcode-middleware`
-**deleted** — the package was withdrawn outright instead of migrated, so there
-is no `packages/middleware` to create and no subsequent fold-into-core step.
-The reversal is recorded here rather than deleted because the instruction it
-replaces was explicit, and a reader who remembers it should be able to see that
-it was changed deliberately and not simply forgotten.
-
-Nothing was lost in capability terms: per-route middleware is **native to
-core** via the `middleware:` array ([MIDDLEWARE.md](MIDDLEWARE.md)), and the
-deleted package only ever offered the same behavior through the extension
-seam. Trust remains the default and explicit sandbox choices keep their
-meaning. The generic extension wrapping hook (`ExtensionInstance.middleware`,
-`RuntimeExtension.cacheSensitive`) stays in core's contract for other
-extensions — it is no longer exercised by any shipped package, which is worth
-knowing before it is assumed to be covered. Static targets continue rejecting
-request-time middleware because there is no server to run it.
-
-Migration scope is therefore **core, auth, admin and UI**. Template and the
-distribution tap stay outside that package move. The observed stale peer pins
-and checkout-limited guidance checks strengthen the case for shared
-verification: carry those checks across the new package paths, since merely
-moving files does not prove every generated skill is covered. The cleanup PRs
-that superseded the earlier zero-open-PR survey have since merged, and a fresh
-survey again reports zero open pull requests across all four in-scope
-repositories — re-run it per repository immediately before that repository
-moves rather than trusting this line.
-
-The [archived monorepo plan](archive/2026-09-19/SPIKE-MONOREPO.md) records
-migration context.
-[Issue 172](https://github.com/jimhoyd-com/urlcode/issues/172), which tracked
-"consolidate middleware into core after moving it into the monorepo," was
-**closed on 2026-09-19** as moot — there was nothing left to consolidate.
-Migration starting is not a claim that it has landed.
-
-## Source review baseline
-
-| Repository | Reviewed commit | Code checked |
-|---|---|---|
-| core | `db375bf` | Runtime dispatch, schema normalization, capabilities, static compiler, prerender, MCP and resource generators |
-| auth | `71957dd` | Lifecycle hooks, UI rendering and shared helper imports |
-| admin | `f3b4882` | UI rendering, auth-service integration and shared helper imports |
-| UI | `0e96f7f` | Shared forms, kit/host exports and copied core contract |
-| ~~middleware~~ | `f201f4b` | Extension wrapping, per-entry sandbox dispatch and scaffolding — **repository deleted 2026-09-19; this baseline is unreachable except through the local `urlcode-middleware.bundle`** |
-| template | `4e09e50` | Exact core pin, generated guide and both vendored skills |
-
-The Homebrew tap (`73eaaef`) still selects stable core `0.3.0`; its old trust
-behavior belongs to that pin and must not be rewritten as alpha.2 behavior.
-The other organization tap and Scoop bucket contain Gitroll, not URLCode.
-The deleted documentation repository is historical context, not a second source
-of current contracts; its former GitHub links no longer resolve. This review is targeted source inspection, not an audit of
-every execution path or an independent security assessment.

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.