# 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.