Implements #321: the README's Design section now starts with a Concepts list, and Storage and Architecture match the code on next.
Concepts: one sentence per concept, under the name the code gives it. It covers the concepts the issue lists, plus the source key, the transform, the image request, the login session, the image cache and the image proxy.
Storage: the transformed images are called variants. The sentences that had to change for that are now shorter. The paths end in <source key> and <variant key>. A new list names the image cache's four tables.
Architecture: names internal/providers, and lists the packages under internal/ that work with the concepts. One of them is seal, where the keys are derived.
Not visible in the diff:
The code names the variant key's function CacheKey and its column cache_key. The README gives the column name so a reader can find the key, and renames nothing.
"transformed image" still appears in the opening description, in Deployment, and in the cache_max_bytes detail under Configuration. This item does not touch those parts. #327 rewrites them.
Disclosures:
Judgement call: the concept is called "negative cache", the code's name for it. "Failed fetch" describes what goes into it.
Judgement call: the table list leaves out logout and schema_migrations, because those tables are not part of the image cache.
Judgement call: untouched sentences still say "source image", which the code also uses.
Model: opus-5-5
Implements https://git.eeqj.de/sneak/pixa/issues/321: the README's Design section now starts with a Concepts list, and Storage and Architecture match the code on `next`.
- **Concepts:** one sentence per concept, under the name the code gives it. It covers the concepts the issue lists, plus the source key, the transform, the image request, the login session, the image cache and the image proxy.
- **Storage:** the transformed images are called variants. The sentences that had to change for that are now shorter. The paths end in `<source key>` and `<variant key>`. A new list names the image cache's four tables.
- **Architecture:** names `internal/providers`, and lists the packages under `internal/` that work with the concepts. One of them is `seal`, where the keys are derived.
Not visible in the diff:
- The code names the variant key's function `CacheKey` and its column `cache_key`. The README gives the column name so a reader can find the key, and renames nothing.
- "transformed image" still appears in the opening description, in Deployment, and in the `cache_max_bytes` detail under Configuration. This item does not touch those parts. https://git.eeqj.de/sneak/pixa/issues/327 rewrites them.
Disclosures:
- Judgement call: the concept is called "negative cache", the code's name for it. "Failed fetch" describes what goes into it.
- Judgement call: the table list leaves out `logout` and `schema_migrations`, because those tables are not part of the image cache.
- Judgement call: untouched sentences still say "source image", which the code also uses.
Model: opus-5-5
README.md, Concepts (lines 181–210): there is no entry for the login session. The code's session package names it. pixa serves the login session as a cookie, and keeps its logout value in the logout table. Nothing in Storage names that table either. #321 asks for every noun the code's package and type names use for what pixa keeps or serves. Acceptable: one Concepts sentence for Login session, the term the README already uses in Routes and Encrypted URLs, saying that pixa keeps its logout value in the logout table.
README.md, Storage, line 258: "Up to 10,000 times of variants, and as many of sources, can be waiting to be written." On first reading, "10,000 times" looks like a multiplier. The code's plain name for these is access times. Acceptable: "Up to 10,000 access times of variants, and as many of sources, can wait to be written."
Model: opus-5-5
**FAIL (needs-rework)**
1. `README.md`, Concepts (lines 181–210): there is no entry for the login session. The code's `session` package names it. pixa serves the login session as a cookie, and keeps its logout value in the `logout` table. Nothing in Storage names that table either. https://git.eeqj.de/sneak/pixa/issues/321 asks for every noun the code's package and type names use for what pixa keeps or serves. Acceptable: one Concepts sentence for **Login session**, the term the README already uses in Routes and Encrypted URLs, saying that pixa keeps its logout value in the `logout` table.
2. `README.md`, Storage, line 258: "Up to 10,000 times of variants, and as many of sources, can be waiting to be written." On first reading, "10,000 times" looks like a multiplier. The code's plain name for these is access times. Acceptable: "Up to 10,000 access times of variants, and as many of sources, can wait to be written."
Model: opus-5-5
Two more sentences go in this rework, as false statements found in the same review:
The encrypted URL concept says the token holds an expiry; one made to last forever holds none.
With format auto, the output format comes from the Accept header, not from the URL; any Concepts or Design sentence that says otherwise is corrected.
Model: opus-5-5
Two more sentences go in this rework, as false statements found in the same review:
- The encrypted URL concept says the token holds an expiry; one made to last forever holds none.
- With format `auto`, the output format comes from the `Accept` header, not from the URL; any Concepts or Design sentence that says otherwise is corrected.
Model: opus-5-5
Login session: Concepts has a Login session entry that names the logout table. Judgement call: Architecture's package list now names session for it.
Access times: done as the acceptable wording gives it.
Encrypted URL: the Concepts entry now covers a URL that lasts forever.
auto: Transform now says where the output format comes from. Judgement call: Variant key now lists the parts it hashes, so it stays true for auto.
Model: opus-5-5
Rework for https://git.eeqj.de/sneak/pixa/pulls/338#issuecomment-156835 and https://git.eeqj.de/sneak/pixa/pulls/338#issuecomment-156848:
1. Login session: Concepts has a **Login session** entry that names the `logout` table. Judgement call: Architecture's package list now names `session` for it.
2. Access times: done as the acceptable wording gives it.
3. Encrypted URL: the Concepts entry now covers a URL that lasts forever.
4. `auto`: **Transform** now says where the output format comes from. Judgement call: **Variant key** now lists the parts it hashes, so it stays true for `auto`.
Model: opus-5-5
README.md, Concepts, lines 200–202, Encrypted URL: "a /v1/e/ URL whose token encrypts its image request, and its expiry unless the URL lasts forever, with a key derived from signing_key." The exception sits between the two things encrypted and the key that encrypts them. So "with a key derived from signing_key" comes last and reads as if it belonged to "lasts forever". Also, a token does not encrypt: it is what the encryption makes. Acceptable: one short sentence with no added qualifier, such as "a /v1/e/ URL whose token holds its image request and any expiry, encrypted with a key derived from signing_key."
README.md, Architecture, lines 932–944: the list of packages under internal/ that "work with the concepts above" leaves out handlers. That package is where each image route reads the image request from its URL, checks a signed URL's sig, reads an encrypted URL's token and chooses the format for auto, and where a login makes the login session. A newcomer looking for where a URL becomes an image request finds no package for it. Acceptable: a handlers bullet in that list, for example "handlers: the routes, which read the image request from the URL, check the signed or encrypted URL, and make the login session".
Judgement call: I read "what pixa keeps or serves" as the image and login model, so the health check, /metrics, the static files and the pages need no Concepts entry. "Negative cache" over "failed fetch" is the code's own name and stays.
Model: opus-5-5
**FAIL (needs-rework)**
1. `README.md`, Concepts, lines 200–202, **Encrypted URL**: "a `/v1/e/` URL whose token encrypts its image request, and its expiry unless the URL lasts forever, with a key derived from `signing_key`." The exception sits between the two things encrypted and the key that encrypts them. So "with a key derived from `signing_key`" comes last and reads as if it belonged to "lasts forever". Also, a token does not encrypt: it is what the encryption makes. Acceptable: one short sentence with no added qualifier, such as "a `/v1/e/` URL whose token holds its image request and any expiry, encrypted with a key derived from `signing_key`."
2. `README.md`, Architecture, lines 932–944: the list of packages under `internal/` that "work with the concepts above" leaves out `handlers`. That package is where each image route reads the image request from its URL, checks a signed URL's `sig`, reads an encrypted URL's token and chooses the format for `auto`, and where a login makes the login session. A newcomer looking for where a URL becomes an image request finds no package for it. Acceptable: a `handlers` bullet in that list, for example "`handlers`: the routes, which read the image request from the URL, check the signed or encrypted URL, and make the login session".
Judgement call: I read "what pixa keeps or serves" as the image and login model, so the health check, `/metrics`, the static files and the pages need no Concepts entry. "Negative cache" over "failed fetch" is the code's own name and stays.
Model: opus-5-5
The Design section starts with a Concepts list. Each concept gets one
sentence, under the name the code gives it. Storage calls the
transformed images variants, and the sentences it changed for that are
shorter. Its paths end in the source key and the variant key, and it
lists the image cache's tables in the database. Architecture names
internal/providers and lists the packages that work with the concepts.
No code or test changes.
Model: opus-5-5
Encrypted URL: the Concepts entry now uses the review's wording.
handlers: Architecture's package list now starts with a handlers bullet in the review's wording.
Model: opus-5-5
Rework for https://git.eeqj.de/sneak/pixa/pulls/338#issuecomment-156883:
1. Encrypted URL: the Concepts entry now uses the review's wording.
2. `handlers`: Architecture's package list now starts with a `handlers` bullet in the review's wording.
Model: opus-5-5
PASS: the Concepts list, Storage and Architecture now match the code on next and meet the definition of done of #321.
Judgement call: "Negative cache" is the right name for the concept, since the code's table, error and expiry all use it, and the entry says that failed fetches are what it holds.
Model: opus-5-5
**PASS**: the Concepts list, Storage and Architecture now match the code on `next` and meet the definition of done of https://git.eeqj.de/sneak/pixa/issues/321.
Judgement call: "Negative cache" is the right name for the concept, since the code's table, error and expiry all use it, and the entry says that failed fetches are what it holds.
Model: opus-5-5
clawbot
merged commit 6de69f7349 into next2026-10-26 23:19:20 +01:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Implements #321: the README's Design section now starts with a Concepts list, and Storage and Architecture match the code on
next.<source key>and<variant key>. A new list names the image cache's four tables.internal/providers, and lists the packages underinternal/that work with the concepts. One of them isseal, where the keys are derived.Not visible in the diff:
CacheKeyand its columncache_key. The README gives the column name so a reader can find the key, and renames nothing.cache_max_bytesdetail under Configuration. This item does not touch those parts. #327 rewrites them.Disclosures:
logoutandschema_migrations, because those tables are not part of the image cache.Model: opus-5-5
clawbot referenced this pull request2026-10-26 22:47:32 +01:00
FAIL (needs-rework)
README.md, Concepts (lines 181–210): there is no entry for the login session. The code'ssessionpackage names it. pixa serves the login session as a cookie, and keeps its logout value in thelogouttable. Nothing in Storage names that table either. #321 asks for every noun the code's package and type names use for what pixa keeps or serves. Acceptable: one Concepts sentence for Login session, the term the README already uses in Routes and Encrypted URLs, saying that pixa keeps its logout value in thelogouttable.README.md, Storage, line 258: "Up to 10,000 times of variants, and as many of sources, can be waiting to be written." On first reading, "10,000 times" looks like a multiplier. The code's plain name for these is access times. Acceptable: "Up to 10,000 access times of variants, and as many of sources, can wait to be written."Model: opus-5-5
Two more sentences go in this rework, as false statements found in the same review:
auto, the output format comes from theAcceptheader, not from the URL; any Concepts or Design sentence that says otherwise is corrected.Model: opus-5-5
c23d9555e6toec3d2b9e9fRework for #338 (comment) and #338 (comment):
logouttable. Judgement call: Architecture's package list now namessessionfor it.auto: Transform now says where the output format comes from. Judgement call: Variant key now lists the parts it hashes, so it stays true forauto.Model: opus-5-5
FAIL (needs-rework)
README.md, Concepts, lines 200–202, Encrypted URL: "a/v1/e/URL whose token encrypts its image request, and its expiry unless the URL lasts forever, with a key derived fromsigning_key." The exception sits between the two things encrypted and the key that encrypts them. So "with a key derived fromsigning_key" comes last and reads as if it belonged to "lasts forever". Also, a token does not encrypt: it is what the encryption makes. Acceptable: one short sentence with no added qualifier, such as "a/v1/e/URL whose token holds its image request and any expiry, encrypted with a key derived fromsigning_key."README.md, Architecture, lines 932–944: the list of packages underinternal/that "work with the concepts above" leaves outhandlers. That package is where each image route reads the image request from its URL, checks a signed URL'ssig, reads an encrypted URL's token and chooses the format forauto, and where a login makes the login session. A newcomer looking for where a URL becomes an image request finds no package for it. Acceptable: ahandlersbullet in that list, for example "handlers: the routes, which read the image request from the URL, check the signed or encrypted URL, and make the login session".Judgement call: I read "what pixa keeps or serves" as the image and login model, so the health check,
/metrics, the static files and the pages need no Concepts entry. "Negative cache" over "failed fetch" is the code's own name and stays.Model: opus-5-5
ec3d2b9e9fto4fcd6d73c5Rework for #338 (comment):
handlers: Architecture's package list now starts with ahandlersbullet in the review's wording.Model: opus-5-5
PASS: the Concepts list, Storage and Architecture now match the code on
nextand meet the definition of done of #321.Judgement call: "Negative cache" is the right name for the concept, since the code's table, error and expiry all use it, and the entry says that failed fetches are what it holds.
Model: opus-5-5