aerie
cloudflare-native port of the tangled knot server
Star
Fork
Watch
aerie UPSTREAM.md
4.7 kB
Markdown
at main

upstream #

upstream base SHA #

UPSTREAM_BASE_SHA: bce1d7901aa43296018772151b1352db981c3811

This is the legacy Go-knot master HEAD at aerie's final broad catch-up, 2026-07-05. Lint gates compare inherited lexicons against this frozen base rather than a moving branch.

upstream remote #

UPSTREAM_REMOTE: tangled.org/tangled.org/core

The canonical upstream source is on tangled.org. Do not target the archived GitHub mirror.

patch categories #

Every aerie commit ends with a Patch category: trailer using one of these values:

  • upstreamable-core: a change that could be offered to Tangled as an upstream PR after it is green in aerie. sol engineers DCO-sign these commits.
  • aerie-distribution: aerie repo governance, Cloudflare distribution work, or sol pbc tooling that is not upstreamable.
  • sol-agent-future: deferred agent-customization work. v1 introduces none of these commits.

scripts/lint-upstreamable-core.sh (wired into make lint) enforces this: any upstreamable-core-tagged commit that touches an aerie-only path (AGENTS.md, COMMUNITY.md, CONTRIBUTING.md, UPSTREAM.md, Makefile, package.json, package-lock.json, top-level wrangler.toml, pr.png, scripts/, deploy/cloudflare/) fails the build. The block-list shape is deliberate. A strict allow-list of "must exist on upstream/master" would misfire on legitimate new-file additions such as the dbdrv/ package.

trailer corrections #

  • a9b1c14e ("Makefile: add test-dual target for mattn+modernc parity testing") is incorrectly labelled Patch category: upstreamable-core. The substantive category is aerie-distribution: the commit modifies only AGENTS.md and Makefile, both aerie-only files (neither exists on upstream/master). The parity-testing discipline (running tests under both mattn and modernc build tags) is upstream-relevant, but a Makefile target is aerie-side affordance, not upstream-shaped code. The mismatch was caught when the commit hit CONFLICT (modify/delete) on cherry-pick to upstream/master. The original commit's SHA and history are preserved; this audit-trail entry is the canonical record. PR 1 (modernc) drops a9b1c14e from its series accordingly.

Each correction above must also have a machine-readable line below. The lint-upstreamable-core.sh gate parses these to skip already-audited commits so a preserved-history correction doesn't leave the lint failing forever. SHA may be short or full; trailing whitespace is tolerated. Format:

TRAILER_OVERRIDE: <sha> <original-category> -> <corrected-category>

TRAILER_OVERRIDE: a9b1c14e upstreamable-core -> aerie-distribution

aerie-only commits #

Use this command to list commits present in aerie and absent from upstream:

git log upstream/master..main --pretty=format:'%h %s'

(Aerie's default branch is main following sol pbc convention; upstream Tangled's default branch is master and stays as-is on the upstream remote.)

current upstream posture #

Tangled replaced the Go knot with a separate Rust implementation, Knot 2. The legacy Go line no longer has a standing upstream PR or rebase cadence. aerie is a sol-owned distribution with independent release timing.

Historical upstreamable-core trailers remain useful provenance: they identify changes that were written in generic Go-knot form. New work should use that category only when it is genuinely useful outside the Cloudflare distribution and has a concrete sharing destination. Upstream acceptance never gates aerie.

known-build-deps #

go list -deps ./cmd/knot was checked for the language detector path. The default ./cmd/knot build graph includes github.com/go-enry/go-enry/v2 packages and does not pull in github.com/go-enry/go-oniguruma.

known-baseline-failures #

None. go test ./... exits 0 at fork-base SHA c2f17d5e (12s wall, all packages pass or have no test files). Run on 2026-05-24.

At the recorded baseline, both go test ./... and go test -tags modernc ./... pass with no documented baseline skips.

updating the frozen Go base #

There is no routine rebase procedure. If a specific legacy Go change must be imported, treat it as a reviewed backport:

  1. pin and record the source commit;
  2. identify the behavior or security contract it changes;
  3. apply the smallest relevant patch to aerie without moving the frozen base marker;
  4. run make ci, the Cloudflare Worker tests, and the affected compatibility/failure tests;
  5. record the backport provenance in this ledger.

A future Knot 2-based aerie line should record its own pinned core revision and adapter boundary. It should not rewrite this Go history or reuse UPSTREAM_BASE_SHA to imply ancestry that does not exist.