tep 0.11.0

data/examples/maidenhead/README.md

@@ -0,0 +1,47 @@
+# maidenhead — a tep app that *fully* runs on an external gem (via a Gemfile)
+
+This app is built entirely on a real published Ruby gem:
+[`maidenhead` 1.0.1](https://rubygems.org/gems/maidenhead) (MIT), the
+ham-radio [Maidenhead Locator System](https://en.wikipedia.org/wiki/Maidenhead_Locator_System)
+converter. It is **declared in a `Gemfile`** and resolved the proper way —
+not hand-vendored.
+
+**Every route exercises the gem, and the entire public API compiles** —
+there is no unsupported-method caveat (contrast the sibling `geohash`
+example, where the gem's hot path works but two helpers need spinel
+features that aren't there yet).
+
+## How a tep app uses a gem (the spinelgems convention)
+
+tep apps are ahead-of-time compiled by spinel — there is no runtime gem
+loader, and spinel has no gem load path. The
+[`bundler-spinel`](https://github.com/OriPekelman/spinelgems) plugin
+(`spinel-compat`) bridges that: it reads a `Gemfile.lock`, places each
+gem's source under `vendor/spinel/<name>/`, and generates
+`vendor/spinel/deps.rb` (a `require_relative` per gem, in lock order). The
+app pulls everything in with one line:
+
+```ruby
+require_relative 'vendor/spinel/deps'
+```
+
+`bin/tep build` inlines that `require_relative` **recursively** (deps.rb
+chains to each gem), so the gems become native compiled code in the
+binary. The `Gemfile` + `Gemfile.lock` are the source of truth and are
+committed; `vendor/spinel/` is generated and gitignored.
+
+## Build + run
+
+```sh
+make vendor-examples           # spinel-compat vendor -> vendor/spinel/ (needs ../spinelgems)
+bin/tep build examples/maidenhead/app.rb -o /tmp/maidenhead
+/tmp/maidenhead -p 4981 &
+
+curl 'http://127.0.0.1:4981/valid?loc=FN31pr'                              # => true
+curl 'http://127.0.0.1:4981/to_latlon?loc=FN31pr'                          # => 41.731076,-72.704514
+curl 'http://127.0.0.1:4981/to_grid?lat=40.7128&lon=-74.0060&precision=3'  # => FN20xr
+```
+
+Each result is identical to CRuby's `Maidenhead.*`.
+`test/test_maidenhead_example.rb` runs the vendor step, builds this app,
+and checks every route against CRuby's output.

data/examples/maidenhead/app.rb

@@ -0,0 +1,46 @@
+require 'sinatra'
+
+# A tep app built entirely on a REAL published Ruby gem -- maidenhead
+# 1.0.1 (MIT), the ham-radio grid-locator <-> lat/lon converter --
+# declared in a Gemfile and resolved the proper way: `spinel-compat
+# vendor` (bundler-spinel, from ../spinelgems) reads Gemfile.lock and
+# places the gem under vendor/spinel/ with a generated deps.rb. We pull
+# it in with the ONE require below; bin/tep inlines the require_relative
+# chain into the AOT binary. Nothing here is hand-vendored. Run
+# `make vendor` (or see README.md) before building. Unlike the geohash
+# example, EVERY route exercises the gem and the whole public API
+# compiles -- no unsupported-method caveat.
+require_relative 'vendor/spinel/deps'
+
+# GET /valid?loc=FN31pr  -> "true" / "false"
+get '/valid' do
+  if Maidenhead.valid_maidenhead?(params["loc"])
+    "true"
+  else
+    "false"
+  end
+end
+
+# GET /to_latlon?loc=FN31pr  -> "41.731076,-72.704514"
+get '/to_latlon' do
+  r = Maidenhead.to_latlon(params["loc"])
+  r[0].to_s + "," + r[1].to_s
+end
+
+# GET /to_grid?lat=40.7128&lon=-74.0060&precision=3  -> "FN20xr"
+get '/to_grid' do
+  lat  = params["lat"].to_f
+  lon  = params["lon"].to_f
+  prec = params["precision"].to_i
+  if prec <= 0
+    prec = 5
+  end
+  Maidenhead.to_maidenhead(lat, lon, prec)
+end
+
+get '/' do
+  "tep + maidenhead 1.0.1 (a real, unmodified published gem)\n" +
+  "try: /valid?loc=FN31pr\n" +
+  "     /to_latlon?loc=FN31pr\n" +
+  "     /to_grid?lat=40.7128&lon=-74.0060&precision=3\n"
+end

data/examples/pg_hello.rb

@@ -0,0 +1,76 @@
+# Tep::PG smoke test app -- exercises the v1 PG battery surface.
+#
+#   GET /             - libpq + server version + a SELECT round-trip
+#   GET /tables       - list user tables in the public schema
+#   GET /error        - issues a deliberate SELECT against a missing
+#                       table, demonstrates the v1 result.ok? check
+#
+# Set PG_URL in the environment (default: postgresql:///postgres,
+# the admin DB on localhost via Unix socket).
+#
+#   PG_URL=postgresql://postgres:postgres@127.0.0.1/postgres \
+#     ./examples/pg_hello -p 4567
+#
+# v1 returns Results-with-ok? rather than raising on error -- spinel's
+# rescue dispatch can't match module-namespaced exception classes
+# today (matz/spinel#627). Once that lands, this example collapses
+# to the AR-shape `rescue PG::Error => e`.
+require_relative "../lib/tep"
+
+PG_URL = ENV["PG_URL"] != nil && ENV["PG_URL"].length > 0 ? ENV["PG_URL"] : "postgresql:///postgres"
+
+get '/' do
+  c = PG.connect(PG_URL)
+  if !c.connected?
+    res.set_status(503)
+    "PG.connect failed: " + c.last_error_message
+  else
+    sv = c.server_version
+    r = c.exec("SELECT 1 AS one, 'hello' AS greeting")
+    body = "libpq " + PG.libpq_version + "\n" +
+           "server_version: " + sv.to_s + "\n" +
+           "row 0: " + r.getvalue(0, 0) + " / " + r.getvalue(0, 1) + "\n"
+    r.clear
+    c.close
+    res.headers["Content-Type"] = "text/plain"
+    body
+  end
+end
+
+get '/tables' do
+  c = PG.connect(PG_URL)
+  r = c.exec("SELECT tablename FROM pg_catalog.pg_tables WHERE schemaname = 'public' ORDER BY tablename")
+  out = "tables (" + r.ntuples.to_s + "):\n"
+  i = 0
+  n = r.ntuples
+  while i < n
+    out = out + "  " + r.getvalue(i, 0) + "\n"
+    i += 1
+  end
+  r.clear
+  c.close
+  res.headers["Content-Type"] = "text/plain"
+  out
+end
+
+# exec raises the SQLSTATE-mapped PG::Error subclass on failure (the
+# ruby-pg / AR shape). Rescue the leaf (PG::UndefinedTable) or the base
+# (PG::Error); the SQLSTATE / message stay on the connection's last_*.
+get '/error' do
+  c = PG.connect(PG_URL)
+  out = ""
+  begin
+    r = c.exec("SELECT * FROM tep_no_such_table")
+    r.clear
+    out = "unexpected: query succeeded"
+  rescue PG::UndefinedTable => e
+    out = "rescued PG::UndefinedTable\n" +
+          "sqlstate: " + c.last_sqlstate + "\n" +
+          "is undefined-table? " + (c.last_sqlstate == "42P01" ? "yes" : "no") + "\n" +
+          "is PG::Error? " + (e.is_a?(PG::Error) ? "yes" : "no") + "\n" +
+          "message: " + e.message
+  end
+  c.close
+  res.headers["Content-Type"] = "text/plain"
+  out
+end

data/examples/qdrant/Gemfile

@@ -0,0 +1,11 @@
+source "https://rubygems.org"
+ruby "3.3.0", engine: "spinel", engine_version: "0.0.0"
+
+# The rejected end of the spectrum. qdrant-ruby is a real, useful gem --
+# but its transport is Faraday and its request bodies are built as
+# incrementally-mutated heterogeneous hashes, neither of which compiles
+# under spinel today. We declare it the same way as the working examples
+# precisely so the spinelgems GATE (`spinel-compat check`) can tell us so,
+# with reasons -- that is the whole point of running gems through
+# spinelgems. See README.md.
+gem "qdrant-ruby", "0.9.10"

data/examples/qdrant/Gemfile.lock

@@ -0,0 +1,29 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    faraday (2.14.2)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.3)
+      net-http (~> 0.5)
+    json (2.19.7)
+    logger (1.7.0)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
+    qdrant-ruby (0.9.10)
+      faraday (>= 2.0.1, < 3)
+    uri (1.1.1)
+
+PLATFORMS
+  aarch64-linux
+  ruby
+
+DEPENDENCIES
+  qdrant-ruby (= 0.9.10)
+
+RUBY VERSION
+   ruby 3.4.9p82
+
+BUNDLED WITH
+   2.6.9

data/examples/qdrant/README.md

@@ -0,0 +1,54 @@
+# qdrant — the rejected end of the spectrum (a spinelgems gate experiment)
+
+This directory has **no app** — on purpose. It's the counterpart to the
+`geohash` and `maidenhead` examples: a real, useful gem
+([`qdrant-ruby`](https://rubygems.org/gems/qdrant-ruby)) that **cannot** be
+used from a tep app today, declared in a [`Gemfile`](Gemfile) precisely so
+the spinelgems compatibility **gate** can tell us *why*. Running gems
+through spinelgems is the point; a clean "no" with reasons is a useful
+result.
+
+## The gate verdict
+
+```sh
+bundle lock
+SPINEL_DIR=/spinel ruby -I $SPINELGEMS/lib $SPINELGEMS/exe/spinel-compat check Gemfile.lock
+```
+
+```
+✗ faraday           2.14.2   rejected  — hard:Mutex.new
+✗ faraday-net_http  3.4.3    rejected  — no-entrypoint
+✗ json              2.19.7   rejected  — c-extension
+✗ logger            1.7.0    rejected  — unresolved:instance_method, …
+✗ net-http          0.9.1    rejected  — no-entrypoint
+✓ qdrant-ruby       0.9.10   clean
+✗ uri               1.1.1    rejected  — unresolved:…
+```
+
+The gem's *own* source is `clean` — but it's unusable, because its entire
+transitive transport stack is rejected:
+
+- **faraday** uses `Mutex.new`, which spinel doesn't support (`hard:`).
+- **json** is a C-extension gem (spinel provides its own `JSON`, but the
+  gem's native build can't be compiled in).
+- **net-http / faraday-net_http** have no spinel entrypoint.
+- **uri / logger** lean on dozens of unresolved stdlib methods.
+
+So unlike `geohash` (gem reuse is per-*method*), qdrant fails at the
+*dependency* level: there's no subset of entry points that avoids Faraday.
+
+## What we proved separately
+
+Even bypassing the gem (raw `Tep::Http` + `JSON.generate`), the Qdrant
+*write* path is blocked by a spinel codegen gap: request bodies are built
+as incrementally-mutated **heterogeneous** hashes (`h["a"]=1; h["b"]="x"`),
+which spinel types homogeneously and fails to compile. A tep-native client
+that builds bodies as *literals* does round-trip against Qdrant Cloud over
+TLS — but that's not "using the gem". See the project memory notes.
+
+## Why this is here
+
+A gem catalog is only trustworthy if the "no"s are as legible as the
+"yes"es. `geohash` + `maidenhead` show what works; `qdrant` shows the gate
+catching what doesn't, with actionable reasons. All three go through the
+same Gemfile + `spinel-compat` path.

data/examples/sinatra_style.rb

@@ -0,0 +1,32 @@
+# Sinatra-classic style. Compile with `bin/tep build sinatra_style.rb`.
+# This file is NOT meant to be passed to spinel directly -- the translator
+# rewrites the do/end blocks into Tep::Handler subclasses first.
+require 'sinatra'   # ignored by translator; documentation-only
+
+set :public_dir, '../public'
+
+get '/' do
+  "<h1>hello, world</h1>" +
+  "<p>This is real Sinatra-style source compiled by spinel via tep.</p>"
+end
+
+get '/hi/:name' do
+  "<p>hi, " + params[:name] + "!</p>"
+end
+
+get '/about' do
+  content_type 'text/plain'
+  "served as plain text\n"
+end
+
+get '/old' do
+  redirect '/'
+end
+
+before do
+  puts "[" + request.verb + "] " + request.path
+end
+
+not_found do
+  "<h1>oops -- " + request.path + " not here</h1>"
+end

data/examples/websocket_echo.rb

@@ -0,0 +1,37 @@
+# Tep WebSocket echo demo.
+#
+# Walks the Sinatra-shaped DSL hook the bin/tep translator lowers
+# into a generated upgrade route + per-event Tep::WebSocket::Handler
+# subclasses. WS support requires the scheduled server (the recv
+# loop parks on Tep::Scheduler.io_wait), so we opt in via
+# `set :scheduler, :scheduled`.
+#
+# Try it:
+#   ./examples/websocket_echo -p 4567
+#   # then from a separate terminal:
+#   websocat ws://127.0.0.1:4567/echo
+#   > hello
+#   < echo: hello
+require_relative "../lib/tep"
+
+set :scheduler, :scheduled
+
+get "/" do
+  "<!doctype html><html><body>" +
+    "<p>WebSocket echo server. Connect to <code>ws://host:port/echo</code>.</p>" +
+    "</body></html>"
+end
+
+websocket "/echo" do |ws|
+  on_open do |evt|
+    ws.text("welcome")
+  end
+
+  on_message do |evt|
+    ws.text("echo: " + evt.data)
+  end
+
+  on_close do |evt|
+    # No-op; placeholder for the user's cleanup path.
+  end
+end

data/lib/tep/agent_delegation.rb

@@ -0,0 +1,35 @@
+# Tep::AgentDelegation -- the "on behalf of" half of a delegated
+# identity. Carries the agent's own id (distinct from the human
+# principal it acts for), the grant timestamps, and the origin
+# label so audit logs can tell apart "issued via OAuth consent" vs
+# "minted from a session handoff" vs "raw API token".
+#
+# Always paired with a Tep::Identity whose principal_id is the
+# human being acted for. An Identity#human? has acting_via == nil;
+# an Identity#agent? has acting_via populated with this struct.
+#
+# Lives in its own file so consumers that want the delegation
+# vocabulary without the full Identity surface can require it
+# narrowly.
+module Tep
+  class AgentDelegation
+    attr_reader :agent_id     # String, e.g. "summarizer-bot"
+    attr_reader :issued_at    # Integer (unix epoch seconds)
+    attr_reader :expires_at   # Integer (unix epoch seconds)
+    attr_reader :origin       # Symbol: :token, :oauth_grant, :session_handoff, ...
+
+    def initialize(agent_id, issued_at, expires_at, origin)
+      @agent_id   = agent_id
+      @issued_at  = issued_at
+      @expires_at = expires_at
+      @origin     = origin
+    end
+
+    # `now` is unix epoch seconds (Time.now.to_i shape). Passed in
+    # rather than read from Time.now so callers control the clock
+    # source (and tests can fast-forward).
+    def expired?(now)
+      now >= @expires_at
+    end
+  end
+end

data/lib/tep/app.rb

@@ -0,0 +1,291 @@
+# Tep::App -- the registered route table + filter slots + 404 handler.
+#
+# Each filter slot holds a single Tep::Filter instance. Spinel's
+# `PtrArray` is homogeneously-typed and doesn't carry cls_id tags,
+# so an array of mixed Filter subclasses falls through to base-class
+# dispatch (the user's #before / #after never runs). A single slot
+# typed as a union of subclasses keeps virtual dispatch working.
+# Users compose multiple filters by writing one class that calls
+# the others.
+module Tep
+  class App
+    attr_accessor :router, :static_root, :session_secret
+    attr_accessor :tls_cert, :tls_key
+    attr_accessor :before_filter, :after_filter, :nf_handler
+    # The auth-filter runs BEFORE before_filter so handler bodies and
+    # user filters always see a populated req.identity. Separate slot
+    # (rather than wedging into before_filter) so user-installed
+    # filters and the auth populate don't fight for the single slot
+    # tep otherwise imposes. Default is a no-op Tep::Filter; the
+    # Auth battery installs Tep::AuthFilter on top via
+    # Tep::Auth.install!.
+    attr_accessor :auth_filter
+    # Shared HS256 secret consumed by Tep::AuthBearerToken. Stored on
+    # APP (rather than a class var) so spinel routes the read through
+    # the canonical instance-attr path.
+    attr_accessor :auth_bearer_secret
+    # Per-process OAuth2 client registry + ephemeral authorization-code
+    # store. See Tep::AuthOAuth2 for the issuance flow.
+    attr_accessor :auth_oauth2_clients
+    attr_accessor :auth_oauth2_codes
+    # Per-process Broadcast subscriber registry. Each entry pairs a
+    # topic with an output fd; publish iterates + writes the payload
+    # to every matching fd.
+    attr_accessor :broadcast_subs
+    # Per-process Presence entry registry. Each entry is one
+    # (principal, session, topic) tracking, with kind/agent_id +
+    # structured-status fields inline. See Tep::Presence.
+    attr_accessor :presence_entries
+    # PG-mirror state for cross-worker visibility. `enabled` is 0
+    # when off, 1 when on. `worker_id` uniquely identifies this
+    # worker's rows in the tep_presence table (PID + boot epoch
+    # so a restart on the same PID isn't aliased). See
+    # Tep::Presence.enable_pg_mirror.
+    attr_accessor :presence_pg_enabled
+    attr_accessor :presence_pg_worker_id
+    attr_accessor :presence_pg_conn
+    # PG-backed cross-worker pub/sub state. `broadcast_pg_enabled`
+    # is 0 when off, 1 when on. The dedicated LISTEN connection
+    # lives in `broadcast_pg_conn`; channel name in
+    # `broadcast_pg_channel`. Configured by
+    # Tep::Broadcast.enable_pg_backend.
+    attr_accessor :broadcast_pg_enabled
+    attr_accessor :broadcast_pg_channel
+    attr_accessor :broadcast_pg_conn
+    # Tep::Llm::OpenAI::Server backend (Battery 7). Set by
+    # Server.use(backend) at boot; the route handlers dispatch through
+    # it per request. Seeded with a base Backend in lib/tep.rb (after
+    # openai_server.rb loads -- not in initialize, since the class
+    # isn't defined yet there), same pattern as broadcast_pg_conn.
+    attr_accessor :openai_backend
+    # Tep::Events emitter for the openai-server (7.1c). Configured by
+    # Server.serve!(events_jsonl); empty path => zero-overhead disabled.
+    # Late-seeded for the same reason as openai_backend.
+    attr_accessor :openai_events
+    attr_accessor :asset_bodies, :asset_mimes, :asset_etags
+    attr_accessor :sched_fibers, :sched_wake_at, :sched_current
+    attr_accessor :sched_io_fd, :sched_io_mode, :sched_io_ready
+    # Tep::Job background-worker idempotency flag. App-level so a
+    # single-shot spawn from a before-filter doesn't fire repeatedly.
+    # Per-worker (each prefork child has its own Tep::APP, so each
+    # worker spawns one background fiber).
+    attr_accessor :user_bg_started
+
+    def initialize
+      @router         = Router.new
+      @static_root    = ""
+      @session_secret = ""
+      @tls_cert       = ""   # inbound TLS cert path (tep#148 ph2; "" = plain HTTP)
+      @tls_key        = ""   # inbound TLS key path
+      @before_filter  = Filter.new   # no-op default
+      @after_filter   = Filter.new
+      @auth_filter    = Filter.new   # no-op until Tep::Auth.install!
+      @auth_bearer_secret = ""
+      # Type-seed the OAuth2 registries with a single dummy entry +
+      # immediate drop so the PtrArray slot type is pinned.
+      @auth_oauth2_clients = [Tep::AuthOAuth2Client.new("_", "", "", [:_])]
+      @auth_oauth2_clients.delete_at(0)
+      @auth_oauth2_codes = [Tep::AuthOAuth2Code.new("_", "", "", "", 0)]
+      @auth_oauth2_codes.delete_at(0)
+      # Same type-seed pattern for the Broadcast subscriber registry.
+      @broadcast_subs = [Tep::BroadcastSubscription.new("_", -1, 0)]
+      @broadcast_subs.delete_at(0)
+      # And for the Presence entry registry.
+      @presence_entries = [Tep::PresenceEntry.new("_", "", :human, "", -1, 0)]
+      @presence_entries.delete_at(0)
+      @presence_pg_enabled   = 0
+      @presence_pg_worker_id = ""
+      @broadcast_pg_enabled = 0
+      @broadcast_pg_channel = ""
+      # Seed broadcast_pg_conn later via lib/tep.rb's setter seed
+      # (APP.set_broadcast_pg_conn(PG::Connection.new(""))) -- module
+      # load order means PG::Connection isn't safely callable from
+      # App#initialize when this is loaded before pg.rb's full surface.
+      @nf_handler     = Handler.new
+      @asset_bodies   = Tep.str_hash # path -> bytes (filled at boot
+      @asset_mimes    = Tep.str_hash # by Tep::Assets._add lines
+                                     # the bin/tep translator emits)
+      @asset_etags    = Tep.str_hash # path -> content-hash ETag (#152)
+      # FiberSlot array for the cooperative scheduler. Initialise
+      # with a noop-bodied slot to pin the array element type, then
+      # drop it. Each slot holds one Fiber + a timer entry in the
+      # parallel `sched_wake_at` int array.
+      @sched_fibers   = [Tep::FiberSlot.new(Fiber.new { Tep.seed_fiber_noop })]
+      @sched_fibers.delete_at(0)
+      @sched_wake_at  = [0]
+      @sched_wake_at.delete_at(0)
+      @sched_current  = -1               # currently-running fiber idx
+                                         # (-1 = scheduler root).
+      # Parallel I/O-wait arrays. `sched_io_fd[i] == -1` means the
+      # fiber isn't parked on I/O (pure timer wait, or ready). When
+      # parked: `sched_io_mode[i]` carries the requested READ/WRITE
+      # bits, and tick() writes back the observed-ready bits into
+      # `sched_io_ready[i]`. io_wait returns those bits to its caller.
+      @sched_io_fd    = [0]
+      @sched_io_fd.delete_at(0)
+      @sched_io_mode  = [0]
+      @sched_io_mode.delete_at(0)
+      @sched_io_ready = [0]
+      @sched_io_ready.delete_at(0)
+      @user_bg_started   = false
+    end
+
+    def add_asset(path, body, mime)
+      @asset_bodies[path] = body
+      @asset_mimes[path]  = mime
+      # Content-hash ETag for cache revalidation (#152). SHA-1 is used
+      # purely as a fast content fingerprint here (not a security hash --
+      # collision resistance is irrelevant for an ETag, same as git's
+      # content addressing). Computed once at boot. (Binary bodies with
+      # embedded NULs hash by their leading bytes via the FFI string
+      # boundary; still stable per content, which is all an ETag needs.)
+      @asset_etags[path] = Crypto.sp_crypto_sha1_hex(body)
+    end
+
+    def set_session_secret(s)
+      @session_secret = s
+    end
+
+    # Inbound TLS cert/key paths (tep#148 phase 2). Set via
+    # Tep.tls_cert= / Tep.tls_key=; read by Tep::Server.run at boot.
+    def set_tls_cert(s)
+      @tls_cert = s
+    end
+
+    def set_tls_key(s)
+      @tls_key = s
+    end
+
+    def add_route(verb, pattern, handler)
+      @router.add(verb, pattern, handler)
+    end
+
+    def set_static_root(root);    @static_root = root; end
+    def set_before(f);            @before_filter = f; end
+    def set_after(f);             @after_filter = f; end
+    def set_auth_filter(f);       @auth_filter = f; end
+    def set_auth_bearer_secret(s); @auth_bearer_secret = s; end
+    def set_broadcast_pg_enabled(v); @broadcast_pg_enabled = v; end
+    def set_broadcast_pg_channel(s); @broadcast_pg_channel = s; end
+    def set_broadcast_pg_conn(c);    @broadcast_pg_conn    = c; end
+    def set_presence_pg_enabled(v);   @presence_pg_enabled   = v; end
+    def set_presence_pg_worker_id(s); @presence_pg_worker_id = s; end
+    def set_presence_pg_conn(c);      @presence_pg_conn      = c; end
+    def set_openai_backend(b);        @openai_backend        = b; end
+    def set_openai_events(e);         @openai_events         = e; end
+    def set_not_found(h);         @nf_handler = h; end
+
+    def dispatch(req, res)
+      # Pull a signed session cookie into req.session, when configured.
+      secret = Tep.session_secret
+      if secret.length > 0
+        cv = req.cookies[Tep::COOKIE_NAME]
+        if cv.length > 0
+          req.session.load_from(cv, secret)
+        end
+      end
+
+      asset_served = false
+      # Auth filter populates req.identity (anonymous or matched
+      # provider's Identity) before the user's before-filter runs,
+      # so user code can always rely on req.identity being set.
+      @auth_filter.before(req, res)
+      if res.halted
+        # Auth filter signalled "deny" -- skip the user filter +
+        # route dispatch, fall through to after-filter + session.
+      end
+      @before_filter.before(req, res)
+      if !res.halted
+        # Bundled assets (everything under <app>/assets/, baked into
+        # the binary by bin/tep) take precedence over the route
+        # table. Match by exact path; on hit we set the body + ct
+        # and skip route dispatch + 404 fallback. The after-filter
+        # and session cookie writing still run normally.
+        if Tep::Assets.serve(req.path, res)
+          asset_served = true
+        end
+      end
+      if !res.halted && !asset_served
+        route = @router.match(req)
+        # `pass` loop: a handler can signal skip-to-next-route by
+        # setting req.passed. Iterate until a handler doesn't pass,
+        # or we run out of matching routes.
+        served = false
+        while route != nil && !served
+          route.fold_captures(req)
+          req.passed = false
+          out = route.handler.handle(req, res)
+          if req.passed
+            idx   = @router.index_of(route)
+            route = @router.match_after(req, idx)
+          else
+            res.set_body_if_empty(out)
+            served = true
+          end
+        end
+        if !served
+          if !try_static(req, res)
+            out = @nf_handler.handle(req, res)
+            res.set_status(404)
+            if out.length > 0
+              res.set_body_if_empty(out)
+            else
+              res.set_body_if_empty("<h1>404 Not Found</h1><p>" +
+                                    req.verb + " " + req.path + "</p>\n")
+            end
+          end
+        end
+      end
+      @after_filter.after(req, res)
+
+      # If the handler / filters mutated the session, sign + emit a
+      # Set-Cookie line. Path=/ so the cookie applies to the whole
+      # app; HttpOnly to keep it out of JS.
+      secret_w = Tep.session_secret
+      if secret_w.length > 0 && req.session.dirty
+        opts = Tep.str_hash
+        opts["Path"]      = "/"
+        opts["HttpOnly"]  = ""
+        opts["SameSite"]  = "Lax"
+        res.set_cookie(Tep::COOKIE_NAME, req.session.to_cookie_value(secret_w), opts)
+      end
+    end
+
+    def try_static(req, res)
+      if @static_root.length == 0
+        return false
+      end
+      if req.verb != "GET" && req.verb != "HEAD"
+        return false
+      end
+      if Tep.str_find(req.path, "..", 0) >= 0
+        return false
+      end
+      full = @static_root + req.path
+      sz = Sock.sphttp_filesize(full)
+      if sz < 0
+        return false
+      end
+      res.headers["Content-Type"] = App.guess_mime(full)
+      res.headers["X-Tep-Static"] = "1"
+      res.send_file(full)
+      true
+    end
+
+    def self.guess_mime(path)
+      lower = path.downcase
+      if lower.end_with?(".html") || lower.end_with?(".htm")
+        return "text/html; charset=utf-8"
+      end
+      if lower.end_with?(".css");  return "text/css"; end
+      if lower.end_with?(".js");   return "application/javascript"; end
+      if lower.end_with?(".json"); return "application/json"; end
+      if lower.end_with?(".png");  return "image/png"; end
+      if lower.end_with?(".jpg") || lower.end_with?(".jpeg"); return "image/jpeg"; end
+      if lower.end_with?(".gif");  return "image/gif"; end
+      if lower.end_with?(".svg");  return "image/svg+xml"; end
+      if lower.end_with?(".txt");  return "text/plain; charset=utf-8"; end
+      "application/octet-stream"
+    end
+  end
+end