DEV Community: Russell Jones

Fixing a metadata collision bug in Waaseyaa's file repository

Russell Jones — Thu, 24 Sep 2026 11:54:41 +0000

Ahnii!

Waaseyaa's packages/media package stores uploaded files behind stream-wrapper URIs like public://images/photo.jpg, and LocalFileRepository keeps each file's metadata (filename, MIME type, owner, size) in a JSON sidecar next to the derived path. The sidecar path came from parse_url(), and parse_url() doesn't know these URIs aren't real hierarchical URLs. That mismatch let two completely different files quietly overwrite each other's metadata. Here's the bug, the fix, and the reconciliation problem a fix like this creates.

The Bug: `parse_url()` Doesn't Know About Stream Wrappers

resolveMetadataPath() used to build a sidecar path from just the scheme and path components parse_url() returned:

$parsed = parse_url($uri);
$scheme = isset($parsed['scheme']) ? $this->sanitizeSegment($parsed['scheme']) : 'public';
$path = isset($parsed['path']) ? trim($parsed['path'], '/') : trim($uri, '/');

$segments = array_filter(explode('/', $path), static fn(string $segment): bool => $segment !== '');

That looks reasonable until you feed it a stream-wrapper URI. public://images/shared.pdf isn't a hierarchical URL — it's a scheme plus a flat, ordered path — but parse_url() still applies RFC 3986 grammar to it, and under that grammar the first segment after // is a host, not a path component. So public://images/shared.pdf parses into host: images, path: /shared.pdf, and resolveMetadataPath() only ever looked at path.

That silently dropped the host segment. Two distinct, documented URIs that happened to share a trailing filename under different directories:

public://images/shared.pdf
public://docs/shared.pdf

collided onto the exact same .../shared.pdf.meta.json sidecar. Save the second file and it silently overwrote the first file's metadata. Delete either one's metadata and both lost it. No exception, no log line — just metadata for a file you never touched disappearing.

The Fix: Treat Every Segment After the Scheme as One Flat Path

The fix stops using parse_url()'s host/path split entirely and instead treats everything after scheme:// as one ordered list of segments:

private function resolveMetadataPath(string $uri): string
{
    $scheme = 'public';
    $rest = $uri;

    if (preg_match('#^([A-Za-z][A-Za-z0-9+.-]*)://(.*)$#s', $uri, $matches) === 1) {
        $scheme = $this->sanitizeSegment($matches[1]);
        $rest = $matches[2];
    }

    $segments = array_filter(explode('/', trim($rest, '/')), static fn(string $segment): bool => $segment !== '');
    $safeSegments = array_map([$this, 'sanitizeSegment'], $segments);

    $target = implode('/', $safeSegments);
    if ($target === '') {
        $target = 'file';
    }

    return rtrim($this->rootDir, '/') . '/' . $scheme . '/' . $target . '.meta.json';
}

Every segment gets sanitized individually and stays in order, so images and docs are preserved as distinct path components instead of one being silently discarded. Traversal confinement under the repository root is unchanged — sanitized .. segments still collapse to _ and can't escape rootDir.

That's a good fix, but it changes the on-disk layout for any URI with more than one segment after the scheme. The reviewers caught two problems that a fix like this can't just wave away.

Problem 1: Upgrading Doesn't Migrate Existing Sidecars

Change how a path is derived and every sidecar an existing install already wrote sits at the old location. On upgrade, load() and delete() would look at the new path and find nothing, silently losing access to metadata that's still sitting on disk one directory over.

The fix deliberately does not add an automatic fallback to the old path on read — a fallback would have to pick a winner among the URIs that used to collide there, which is exactly the silent-data-loss failure mode being fixed in the first place. Instead, reconcileLegacySidecars() is a one-time migration operators run explicitly:

It scans every *.meta.json sidecar under the repository root and reads the uri each one recorded at save time.
If a sidecar is already at its current-layout location, it's left alone.
If it isn't, and nothing already exists at the new location, it's relocated there — the common case, since there's exactly one candidate on disk.
If something already exists at the new location (a real conflict — two live candidates for one URI), the legacy sidecar is left untouched and reported as a conflict, never silently overwritten.

It's idempotent, so running it twice on an already-reconciled tree reports nothing to do. The candidate list is collected up front before any renaming happens, because mutating files mid-walk on a RecursiveDirectoryIterator has undefined visitation order.

Problem 2: `save()` Wasn't Atomic

The original save() wrote sidecars with a direct file_put_contents() to the existing path — a truncate-then-rewrite of the same inode. A concurrent load() opening that file mid-write could read a partial, possibly non-JSON-decodable body.

The fix is the standard write-to-temp-then-rename pattern:

private function writeAtomically(string $path, string $payload): void
{
    $directory = dirname($path);
    $temporary = tempnam($directory, '.meta-');
    if (!is_string($temporary)) {
        throw new \RuntimeException(sprintf('Unable to create a temporary file beside %s.', $path));
    }

    try {
        if (file_put_contents($temporary, $payload) !== strlen($payload)) {
            throw new \RuntimeException(sprintf('Unable to write file metadata: %s', $path));
        }

        if (!rename($temporary, $path)) {
            throw new \RuntimeException(sprintf('Unable to move file metadata into place: %s', $path));
        }
    } catch (\Throwable $exception) {
        if (is_file($temporary)) {
            unlink($temporary);
        }

        throw $exception;
    }
}

The temp file lives in the same directory as the target, so rename() stays on one filesystem and is a single atomic directory-entry swap. A reader only ever sees the complete old sidecar or the complete new one — never a partial write. Any failure along the way cleans up the temp file instead of leaving it behind.

Verifying It

The test suite added eight cases specifically to close coverage gaps the CI gate flagged (73.21% on the new code), on top of the regression tests for the original collision fix:

Case	What it proves
Distinct authorities, same relative path	`public://images/shared.pdf` and `public://docs/shared.pdf` save, load, and delete independently
Traversal-sanitized paths	`..` segments still collapse and stay confined to the repository root
Empty root directory	`reconcileLegacySidecars()` on a not-yet-created root returns `[]`
Corrupt or missing `uri` in a legacy sidecar	Reported as `unreadable`, doesn't abort the pass
Legacy sidecar with a conflicting target	Left untouched, reported as `conflict`, never overwritten
Already-reconciled tree	A second run reports nothing to do (idempotent)
`save()` against an existing sidecar	The write swaps the file's inode, proving rename-based replacement
Rename failure during `writeAtomically()`	Cleans up the temp file, throws `RuntimeException`

The General Lesson

parse_url() is built for real URLs, and stream-wrapper URIs like scheme:// only look like them. Feeding a flat, ordered identifier through a parser that assumes host/path semantics will happily produce a result — it just won't be the result you meant, and nothing will tell you that at runtime. The two-line diff that dropped one path segment didn't fail loudly; it just started routing some writes to the wrong file.

The other lesson is about what "fix the derivation" actually obligates you to do. Changing how a path is computed is easy. Owning up to the fact that existing installs have data sitting at the old derivation is the harder part. Giving them an explicit, conflict-reporting way to bring it forward — instead of a silent fallback that would repeat the same bug in miniature — is the work that's easy to punt to a follow-up ticket and never ship.

Baamaapii

Configuring identity-only OAuth requests in Waaseyaa

Russell Jones — Thu, 24 Sep 2026 11:54:37 +0000

Ahnii!

Waaseyaa's oauth-provider package wraps Google and GitHub OAuth 2.0 behind one OAuthProviderInterface. Until recently, both bundled providers only knew how to over-ask: Google always requested offline access with a forced consent prompt, and GitHub always made a second API call for the user's email, even when a consumer just needed a stable, verified identity to log someone in. The package now takes optional constructor arguments so an identity-only consumer can say exactly that, without touching the interface or forking the provider. What follows is the over-asking, the additive fix, and the two unsafe casts that got hardened along the way.

What Over-Asking Looked Like

Before this change:

GoogleOAuthProvider::getAuthorizationUrl() hardcoded access_type=offline and prompt=consent into every authorization URL. Every login requested refresh-token eligibility and forced a re-consent screen, whether or not the consumer ever stored a refresh token.
GitHubOAuthProvider::getUserProfile() called GET /user and then unconditionally called GET /user/emails, even for a consumer that only reads the numeric id GitHub already returns from GET /user.
Optional profile fields were unsafe. Google's email/name were read with a bare (string) $data['email'] cast, and GitHub's name fallback cast $userData['login'] the same way. A response missing either key triggered an "Undefined array key" warning; a malformed non-string value (an array, say) triggered an "Array to string conversion" warning and silently became the string 'Array'. Waaseyaa's phpunit.xml.dist sets failOnWarning="true", so either defect turned into a hard test failure, not a quietly-ignored notice.

Additive Configuration, Not a Parameter Bag

The fix rejected two easier options: a generic array $options bag on either provider (arbitrary, unvalidated URL rewriting) and a single IdentityOnlyMode toggle (which would have silently coupled scopes and refresh-token eligibility — concerns the interface already keeps separate). Instead, both providers gained optional trailing constructor parameters that default to the old behavior:

Provider	Default (unchanged)	Identity-only
Google	`accessType: Offline`, `forceConsent: true` → `access_type=offline&prompt=consent`	`accessType: Online`, `forceConsent: false` → `access_type=online`, `prompt` omitted entirely
GitHub	`fetchEmail: true` → `GET /user` then `GET /user/emails`	`fetchEmail: false` → only `GET /user`; profile has `email: ''`, `emailVerified: false`

A new @api enum backs the Google option instead of a raw string:

enum GoogleAccessType: string
{
    case Offline = 'offline';
    case Online = 'online';
}

GoogleOAuthProvider builds the authorization URL from it, and only adds prompt when consent is forced:

$params = [
    'client_id'     => $this->clientId,
    'redirect_uri'  => $this->redirectUri,
    'response_type' => 'code',
    'scope'         => implode(' ', $scopes),
    'state'         => $state,
    'access_type'   => $this->accessType->value,
];

if ($this->forceConsent) {
    $params['prompt'] = 'consent';
}

return self::AUTH_URL . '?' . http_build_query($params);

Per Google's docs, online is already the default when access_type is absent — so omitting prompt lets Google decide whether re-consent is needed instead of the framework forcing it. forceConsent is independent of accessType: turning off the prompt doesn't silently flip an offline consumer to online access.

GitHubOAuthProvider skips the secondary lookup entirely rather than making the call and discarding the result:

$email = '';
$emailVerified = false;
if ($this->fetchEmail) {
    $emailsResponse = $this->httpClient->get(self::EMAILS_URL, $headers);
    if ($emailsResponse->isSuccess()) {
        foreach ($emailsResponse->json() as $entry) {
            // ...find the primary, verified email
        }
    }
}

The existing fail-loud checks are untouched on both providers: a non-2xx response, a missing or empty id, both still block. An identity-only configuration still refuses a failed or unidentifiable response. It just stops paying for a lookup it would discard.

Using It

use Waaseyaa\OAuthProvider\Provider\GoogleAccessType;
use Waaseyaa\OAuthProvider\Provider\GoogleOAuthProvider;
use Waaseyaa\OAuthProvider\Provider\GitHubOAuthProvider;

// Google: online access, no forced re-consent prompt.
$google = new GoogleOAuthProvider(
    clientId: $clientId,
    clientSecret: $clientSecret,
    redirectUri: $redirectUri,
    httpClient: $httpClient,
    accessType: GoogleAccessType::Online,
    forceConsent: false,
);

// GitHub: skip the secondary /user/emails lookup.
$github = new GitHubOAuthProvider(
    clientId: $clientId,
    clientSecret: $clientSecret,
    redirectUri: $redirectUri,
    httpClient: $httpClient,
    fetchEmail: false,
);

The existing four-argument constructor call on either class still compiles. It still produces byte-identical behavior — offline access with a forced prompt for Google, an email lookup for GitHub. An offline consumer that stores a refresh token, or one that needs a verified GitHub email, just keeps using the defaults.

Hardening the Optional Fields

The unsafe casts got fixed alongside the new parameters, since identity-only responses are exactly where a missing email or name shows up in practice. Google's profile parsing now guards both fields:

$email = isset($data['email']) && is_string($data['email']) ? $data['email'] : '';
$name = isset($data['name']) && is_string($data['name']) ? $data['name'] : '';

GitHub's name fallback got the same treatment — falling back to '' instead of casting a missing or non-string login. The required identity check is unchanged on both providers: a non-2xx response or an absent id still throws before any optional-field logic runs. Only the optional path stopped assuming the upstream payload is well-formed.

Why This Matters Beyond Waaseyaa

Prefer optional, default-preserving parameters over a config bag. A typed enum plus a couple of booleans is auditable at a glance; a generic array $options invites arbitrary, unvalidated behavior that's hard to review.
Don't make a call you'll discard the result of. If a consumer configures identity-only, skip the secondary request outright rather than fetching and ignoring it — it's fewer round trips and one less thing that can rate-limit you.
Optional response fields need isset() and a type check, not a bare cast. Any code path that only exercises the full/happy response will pass tests right up until a real provider omits a field you assumed was always present.

Baamaapii

Host-bound session and CSRF cookies in Waaseyaa

Russell Jones — Thu, 24 Sep 2026 11:54:02 +0000

Ahnii!

The __Host- cookie prefix is one of the stronger security guarantees browsers give you: a cookie named __Host-something can only be set and read by the exact origin that set it, no matter how many subdomains share the parent domain. That closes a real attack: a compromised or malicious subdomain writing a cookie that your main app then trusts as its own session.

The catch is that __Host- isn't a flag you flip. It's a contract with four parts, and if your server violates any one of them, the browser doesn't reject the request or throw an error — it just silently drops the cookie. Waaseyaa recently added a host_bound mode to its SessionCookiePolicy that enforces the full contract for both the session cookie and the CSRF cookie, and refuses to boot if the configuration can't satisfy it. What follows is the four-part contract, how host_bound enforces it for both cookies, and where it refuses to boot instead.

The Four Constraints

A cookie name starting with __Host- is only valid if all of these hold at once:

No Domain attribute. The cookie must be host-only — omitting Domain scopes it to the exact host, not Domain=example.com which would let subdomains see it too.
Path=/. Any narrower path is rejected.
Secure is set. The cookie only travels over HTTPS.
Secure context, implicitly. The cookie has to originate from a secure context in the first place — Secure alone doesn't retroactively fix an insecure origin.

Get any of these wrong and the browser doesn't error — it drops the Set-Cookie header for that cookie entirely. Your session cookie silently never gets set, a user hits a login loop, and there's no log line pointing at the cause. That's the gap Waaseyaa's host_bound option closes: instead of trusting config to be correct, it validates the contract at construction time.

One Policy, Two Cookies

Waaseyaa mints two cookies that need the same hardening:

The PHP session cookie.
The CSRF double-submit cookie (XSRF-TOKEN by default), read by Inertia's axios adapter and forwarded as the X-XSRF-TOKEN header on every mutation.

Before this change, CsrfMiddleware hard-coded the XSRF-TOKEN name. Now both cookies are governed by the same session.cookie config, resolved through SessionCookiePolicy:

final class SessionCookiePolicy
{
    public const DEFAULT_CSRF_COOKIE_NAME = 'XSRF-TOKEN';
    public const HOST_BOUND_SESSION_COOKIE_NAME = '__Host-waaseyaa_session';
    public const HOST_BOUND_CSRF_COOKIE_NAME = '__Host-XSRF-TOKEN';

    private const array SECURE_COOKIE_DEFAULTS = [
        'httponly' => true,
        'secure' => 'auto',
        'samesite' => 'Lax',
        'use_strict_mode' => true,
        'path' => '/',
        'csrf_name' => self::DEFAULT_CSRF_COOKIE_NAME,
        'host_bound' => false,
    ];
}

Setting session.cookie.host_bound => true switches both cookies to the __Host- profile:

Attribute	Default	Host-bound
`Secure`	Follows the `secure` setting (`'auto'`)	Forced on, regardless of `secure`
`Path`	Configurable	Forced to `/`
`Domain`	Configurable	Forced unset
Cookie name	`waaseyaa_session` / `XSRF-TOKEN`	`__Host-waaseyaa_session` / `__Host-XSRF-TOKEN` (or an explicit `__Host-`-prefixed override)

SessionMiddleware applies the resolved policy to the PHP session cookie ini. CsrfMiddleware applies the same policy object to the CSRF cookie. Same source, so the two cookies can't drift out of sync.

Rejected at Construction, Not Discovered in the Browser

The policy validates the whole contract when it's built, before a single request is handled:

private function assertConfigurationCompatible(): void
{
    if (!$this->hostBound()) {
        // non-host-bound cookie name validation
        return;
    }

    $path = $this->path();
    if ($path !== '/') {
        throw new InvalidSessionCookiePolicyException(sprintf(
            'Host-bound session cookies require path "/", got "%s".',
            $path,
        ));
    }

    $domain = $this->options['domain'] ?? null;
    if (is_string($domain) && $domain !== '') {
        throw new InvalidSessionCookiePolicyException(sprintf(
            'Host-bound session cookies must omit Domain; got "%s".',
            $domain,
        ));
    }

    $secure = $this->options['secure'];
    if ($secure !== 'auto' && !filter_var($secure, FILTER_VALIDATE_BOOLEAN)) {
        throw new InvalidSessionCookiePolicyException(
            'Host-bound session cookies require secure=true (or auto); secure=false is incompatible.',
        );
    }

    $sessionName = $this->sessionName();
    if ($sessionName === null || !str_starts_with($sessionName, '__Host-')) {
        throw new InvalidSessionCookiePolicyException(sprintf(
            'Host-bound session cookie name must use the __Host- prefix; got "%s".',
            (string) $sessionName,
        ));
    }
    // same check repeated for the CSRF cookie name
}

If you set host_bound => true and also set an explicit Domain, or a non-root Path, or secure => false, the app refuses to start. That trade-off is deliberate: a config error that fails loudly in CI or on deploy is recoverable. A config error that fails silently in production means some users can't log in, and there's no exception anywhere to explain why.

The policy also checks already-active PHP sessions, not just fresh config. If something upstream (another bootstrap path, an inherited php.ini) already started a session before the policy runs, assertCompatibleWithActiveSession() compares the live session_name() and session_get_cookie_params() against the resolved policy and throws if they disagree — catching the case where host-bound mode is configured but a prestarted session is still running under the old, non-__Host- name.

Malformed Config Is Rejected Too

Beyond the host-bound-specific checks, the policy rejects structurally unsafe values on construction regardless of mode — a path or domain containing a ; (which would inject another Set-Cookie attribute) or control characters, and a non-boolean host_bound value:

if (array_key_exists('host_bound', $options)) {
    $parsed = filter_var(
        $options['host_bound'],
        FILTER_VALIDATE_BOOLEAN,
        FILTER_NULL_ON_FAILURE,
    );
    if ($parsed === null) {
        throw new InvalidSessionCookiePolicyException(
            'session.cookie.host_bound must be a boolean (or a documented boolean string such as "true"/"false").',
        );
    }
    $options['host_bound'] = $parsed;
}

Documented legacy string forms ("1", "0", "on", "off") still parse correctly — this rejects garbage, not backward compatibility.

What Consumers See

None of this changes how Inertia/Vue or vanilla fetch consumers read the CSRF cookie — that contract is unchanged:

<script setup lang="ts">
import { useForm } from '@inertiajs/vue3'

const form = useForm({ file: null as File | null })

function submit() {
  form.post('/ingest/upload', { forceFormData: true })
  // Inertia's axios reads the cookie and forwards X-XSRF-TOKEN automatically.
}
</script>

Inertia's adapter looks for a cookie literally named XSRF-TOKEN unless you tell it otherwise. That's why the Admin SPA's cookie readers were unified into one shared decoder (packages/admin/app/utils/csrfCookie.ts) that reads the configured csrfCookieName from runtime config, rather than each consumer hard-coding the default name. When host-bound mode renames the cookie to __Host-XSRF-TOKEN, every packaged Admin HTML response — the SPA fallback and the prebuilt .html assets — has that name rewritten into it from the runtime policy, so the served bundle and the actual cookie name never disagree.

Why This Matters Beyond Waaseyaa

The pattern generalizes past this one framework:

If you support __Host--prefixed cookies anywhere, validate the full contract programmatically, not just at code review. The failure mode is silent.
When two cookies (session + CSRF) share a security posture, govern them from one policy object, not two copies of the same logic that can drift.
Prefer rejecting bad config at boot over "best-effort" defaults that paper over a mistake. A crash on deploy is a bug report with a stack trace. A silently dropped cookie is a support ticket with no clues.

Baamaapii

Claude Code and Codex skills are directories, not files

Russell Jones — Thu, 24 Sep 2026 11:53:57 +0000

Ahnii!

If you're building tooling that installs "skills" for AI coding agents, it's tempting to treat a skill as just another markdown file you drop somewhere in the repo. It isn't. Both Claude Code and OpenAI Codex discover skills by walking the project tree for a directory that contains a SKILL.md file, not a flat file. Here's what each client actually looks for, the bug a shape mismatch causes, and how Waaseyaa's installer package, Bimaaji, fixed it by sharing one renderer across both clients instead of maintaining two.

What Claude Code actually discovers

A Claude Code project skill lives at:

.claude/skills/<skill-name>/SKILL.md

Two details matter here:

The command name comes from the directory name, not from the name field in the file's frontmatter. The frontmatter name is only the display label shown in skill listings.
Frontmatter is only recognized when the opening --- is the file's first line. If anything precedes it — a comment, a blank line, a provenance marker — Claude Code won't parse it as frontmatter at all.

A flat .claude/skills/<name>.md file is not a documented layout, and Claude Code doesn't discover it. Bimaaji's installer originally emitted exactly that flat shape, and every "file written" count it reported was quietly counting output the client would never load.

What Codex actually discovers

Codex's convention is split in two:

A root AGENTS.md for always-loaded project guidance — the same vendor-neutral file Devin Desktop and JetBrains Junie read.
Detailed, on-demand skills under .agents/skills/<skill-name>/SKILL.md, discovered by walking from the current working directory up to the repository root.

Codex's per-skill directory shape is the same structural contract as Claude Code's: a directory per skill, a SKILL.md inside it, name/description metadata in frontmatter. Bimaaji's installer used to fold every skill body straight into AGENTS.md as one consolidated file. That worked, in the sense that Codex could read it, but it threw away the on-demand loading both clients are designed around — the whole point of a skill is that its detail loads only when needed, not on every request.

The fix: one renderer, not two

Once both clients turned out to want the same shape — a concise always-loaded guidance file plus one SKILL.md per skill — Bimaaji stopped maintaining separate Claude and Codex renderers and introduced a shared base class both transformers extend. Each subclass supplies only two things:

its client id (claude or codex)
its guidance file's title line

Everything else — the per-skill file layout, whether frontmatter is required, the guidance index, and a provenance footer — comes from the shared renderer plus a small per-client capabilities lookup (skill file paths, whether frontmatter must sit at byte zero, and so on).

That provenance footer is the detail worth stealing for your own installers. Two pieces of metadata do the work:

Every generated skill file carries an HTML-comment footer with the sha256 of the whole skill inventory it was rendered from.
The guidance index lists each skill's own source sha256 next to its target path.

Together they let you prove, rather than assume, that Claude and Codex regenerated their skill files from the same canonical source — and that the two clients' output is byte-identical for the same input.

Claude Code vs. Codex, side by side

	Claude Code	Codex
Always-loaded guidance	`.claude/CLAUDE-WAASEYAA.md` (kept separate from a consumer's own `CLAUDE.md`)	root `AGENTS.md`
Per-skill file	`.claude/skills/<skill-name>/SKILL.md`	`.agents/skills/<skill-name>/SKILL.md`
Discovery key	directory name	directory name
Frontmatter required at byte zero	yes	per capability lookup
Command name source	directory name, not frontmatter `name`	directory name

What this means if you're building similar tooling

Don't trust your own success counters. A "files written" count that doesn't check whether the client's discovery mechanism actually finds those files will lie to you convincingly.
Cite the client's own docs, not an issue description. Bimaaji's changelog is explicit that the Codex per-skill layout only shipped once there was a citable, verified discovery mechanism from OpenAI's own docs — not because it seemed like a reasonable guess.
One renderer beats one renderer per client once you notice two clients want the same shape. Two copies of "how a skill file gets rendered" is exactly the kind of thing that drifts quietly.

Baamaapii

Building a conformant stdio MCP server in PHP

Russell Jones — Wed, 16 Sep 2026 14:16:24 +0000

Ahnii!

MCP lets a coding agent call tools over a small JSON-RPC 2.0 protocol. The simplest transport for it is stdio: the agent spawns your process, writes requests to its stdin, and reads responses from its stdout. Waaseyaa's packages/cli package ships exactly that, as a mcp:serve command backing a StdioMcpServer class. Getting stdio right turned out to hinge on a handful of rules that have nothing to do with MCP specifically and everything to do with sharing a byte stream with a client that trusts every byte on it.

Only One Thing May Write to Stdout

A stdio JSON-RPC server's entire contract is: every line on stdout is a complete JSON-RPC frame, and nothing else is ever written there. Break that contract once and every frame after it is garbage - there's no delimiter to resync on. A stray echo, a PHP warning printed to stdout, or a library that logs a banner is all it takes.

StdioMcpServer treats this as a structural rule, not a habit: exactly one private method ever touches the output stream.

private function writeFrame(array $frame): void
{
    $encoded = json_encode($frame, \JSON_THROW_ON_ERROR | \JSON_UNESCAPED_SLASHES);
    fwrite($this->out, $encoded . "\n");
    fflush($this->out);
}

Everything else - parse errors, unhandled exceptions, operator notes - goes through a separate $diagnostic closure the caller wires to stderr instead. Even a crash follows that rule: a \Throwable that escapes a tool dispatch gets a fixed, sanitized message on stderr and a generic -32603 Internal error frame on stdout, never the exception's own message, which could contain a credential or an absolute machine path.

Bounding a Read That Has No Natural Limit

Stdin doesn't tell you how long a line is before you've read it. PHP's fgets() will happily keep growing a buffer until it finds a newline, which means one misbehaving or hostile caller can exhaust the process before your protocol layer gets a chance to reject it with a proper error.

The fix is to give fgets() a hard ceiling - 1 MiB (1,048,576 bytes) - and treat "the ceiling was hit with no newline" as its own case:

public const int MAX_FRAME_BYTES = 1_048_576;

public function run(): int
{
    while (($line = fgets($this->in, self::MAX_FRAME_BYTES + 2)) !== false) {
        if (!$this->isCompleteBoundedFrame($line)) {
            $this->discardRemainderOfOversizedFrame($line);
            $this->writeError(null, StdioJsonRpcErrorCode::INVALID_REQUEST,
                \sprintf('Invalid Request: frame exceeds %d bytes.', self::MAX_FRAME_BYTES));
            continue;
        }
        // ... decode and route the line
    }
    return 0;
}

The +2 matters: it's the room for a maximum-size payload plus its own terminating newline, so a legitimate frame that exactly fills the limit isn't mistaken for an oversized one. When a frame is oversized, the server still has to drain the rest of that line off the stream before it can read the next one - otherwise the leftover bytes get parsed as the start of the following request.

The JSON Object/Array Ambiguity

PHP's json_decode($json, true) erases a distinction JSON-RPC actually cares about: both {} and [] decode to the same empty PHP array, and a non-empty JSON array decodes to a PHP list that is_array() can't tell apart from an object. A params field is supposed to be an object; a naive is_array($params) check would silently accept "params": [1, 2, 3] and hand a handler a value it can't read $params['name'] off of - producing a confusing downstream error for what's really a malformed frame.

private static function isDecodedJsonObject(mixed $value): bool
{
    return \is_array($value) && ($value === [] || !array_is_list($value));
}

A non-empty list is unambiguously a JSON array and gets rejected. The empty array is genuinely ambiguous - it's what both {} and [] decode to - and gets accepted, because every handler in the server treats an empty params object and an absent one identically anyway.

The request ID gets the same strict treatment. JSON-RPC allows a string, a number, or null for id, but MCP narrows that to "string or integer, never null." StdioMcpServer takes the narrower rule and rejects anything else - including a fractional number - with a null-id error response rather than echoing the bad value back, since an object or array id echoed into a response frame would itself be malformed.

Telling Old Clients From New Ones

MCP's protocol revisions split into two eras that don't mix.

	Handshake era (through `2025-11-25`)	Modern era (from `2026-07-28`)
Version negotiation	Client sends `initialize`; server responds with the version it's willing to speak	Every request carries its own protocol version
Startup sequence	Client must send `notifications/initialized` before anything else	No handshake - any method can be called first
Discovery	Not part of the protocol	Server must implement `server/discover`

StdioMcpServer only implements the handshake lifecycle, so it only ever negotiates a handshake-era revision:

final class StdioMcpProtocol
{
    public const string LATEST_HANDSHAKE_REVISION = '2025-11-25';

    public const array SUPPORTED = [
        self::LATEST_HANDSHAKE_REVISION,
        '2025-06-18',
    ];

    public static function negotiate(string $requested): string
    {
        return \in_array($requested, self::SUPPORTED, true)
            ? $requested
            : self::LATEST_HANDSHAKE_REVISION;
    }
}

The interesting part isn't the negotiation - it's what happens when a modern-era client probes this server first. The spec's own recommendation is that a dual-era client should call server/discover before anything else, and fall back to the handshake if it gets an error that isn't specifically one of the modern protocol's own recognized codes.

StdioMcpServer answers server/discover, along with every other method it doesn't know, with a plain -32601 Method not found. That's deliberate. It's the exact signal a dual-era client is watching for to know it should fall back to initialize. Answering with a recognized modern-era error, or answering server/discover at all, would make this server look modern and break that fallback.

Resolving the Interpreter Without Trusting PATH

The last piece is mundane but easy to get wrong: how does a launcher know what command to run to start the server? The obvious answer is "command": "php". That depends on php being on the launching process's PATH, which isn't guaranteed on every platform or every editor's spawn environment.

StdioServerExecutableResolver sidesteps PATH entirely. It resolves the interpreter the same way the framework's dev server does: through PHP_BINARY, an absolute path PHP resolves for itself, never a bare name searched on PATH.

public static function resolve(
    string $projectRoot,
    ?string $phpBinary = null,
    string $profile = self::DEFAULT_PROFILE,
): array {
    $php = $phpBinary ?? \PHP_BINARY;
    // ...
    return [
        'command' => $php,
        'args' => ['-d', 'display_errors=stderr', $normalizedRoot . '/vendor/bin/waaseyaa', 'mcp:serve', '--profile=' . $profile],
    ];
}

The -d display_errors=stderr flag does real work too. It's applied before PHP even loads the target script, so a bootstrap or autoload warning can't land on stdout and corrupt the JSON-RPC stream before the server has a chance to enforce its own one-writer rule.

The General Lesson

None of this is MCP-specific. Any time you put a JSON-RPC (or line-delimited-anything) protocol on top of a raw byte stream, you inherit a short list of problems that have nothing to do with your actual RPC methods:

Who is allowed to write to the stream
What happens when a read has no natural length limit
Whether your decoder throws away a distinction your protocol needs
How a client on a newer version of your protocol recognizes that you're older

Skip any one of those and the bug doesn't show up as a clean error. It shows up as a corrupted frame, an exhausted process, or a client that can't tell what it's talking to.

Baamaapii

Fixing a silent message-drop bug in Waaseyaa's queue worker

Russell Jones — Mon, 14 Sep 2026 12:22:26 +0000

Ahnii!

Waaseyaa's packages/queue package runs background jobs through a Worker that pops a message off a transport and hands it to whichever handler in its roster supports() that message type. If nothing in the roster claimed a message, the worker didn't fail the delivery — it just finished the loop, returned normally, and acknowledged the message as done. Here's the bug, the fix, and why "no handler matched" needs to be a failure, not a no-op.

The Bug: An Empty Loop Still Counts as Success

Worker::handleMessage() walked the handler list looking for the first one that supported the message:

private function handleMessage(object $message): void
{
    foreach ($this->handlers as $handler) {
        if ($handler->supports($message)) {
            $handler->handle($message);

            return;
        }
    }
}

If no handler supports the message, the loop just runs out. The method returns void either way, so from the caller's point of view a message nobody handled looks identical to a message a handler successfully processed. processJob() treats that return as success and acks the delivery:

try {
    // ... envelope/occurrence handling ...
    $this->handleMessage($message);
    // ...
    $this->transport->ack($raw['id']);
} catch (\Throwable $e) {
    $this->handleFailure($raw, $queue, $message, $e, $options, $envelope?->occurrence);
}

QueueInterface/DbalQueue accept any object for dispatch, not just Job — but the worker's own handler roster, by default, only knows how to run Job. Dispatch a plain message object with no registered handler and the worker pulls it off the queue, runs an empty loop, and acks it. No retry, no dead-letter row, nothing written to the failed-job repository. The durable row just disappears, and nothing downstream can tell the difference between "handled" and "nobody was listening."

The Fix: Throw Instead of Falling Through

The fix adds a typed, payload-free exception:

final class UnhandledQueueMessage extends \RuntimeException
{
    public function __construct(object $message)
    {
        parent::__construct(sprintf(
            'No queue handler supports message type "%s".',
            $message::class,
        ));
    }
}

and handleMessage() throws it once the roster is exhausted instead of returning:

private function handleMessage(object $message): void
{
    foreach ($this->handlers as $handler) {
        if ($handler->supports($message)) {
            $handler->handle($message);

            return;
        }
    }

    throw new UnhandledQueueMessage($message);
}

That single throw is enough to route an unsupported message through machinery processJob() already had for every other kind of failure. A few things about that path are worth calling out:

It reuses the existing retry policy. The catch block hands the exception to handleFailure(), which applies the worker's normal bounded retry/backoff — Job::$tries for jobs, WorkerOptions::$maxTries otherwise (three attempts by default for non-Job messages).
The failure record names only the class, not the payload. UnhandledQueueMessage's message is No queue handler supports message type "..." — useful for an operator, safe to log.
Ordering matters. The failed-job row is persisted before the delivery is rejected. If the failed-job repository itself is down, the rejection doesn't happen either, so the message stays reserved for lease recovery instead of being lost a second way.
Nothing about dispatch changed. QueueInterface still accepts any object. This isn't about narrowing what you're allowed to queue — it's about not silently discarding what the worker can't run.

The package README now says this out loud instead of leaving it to be discovered:

Persistent dispatch accepts any object, but successful consumption requires a supporting worker handler. If no handler supports an accepted message, Worker raises a typed UnhandledQueueMessage failure and applies its configured bounded retry/backoff policy. On exhaustion, the signed payload and failure are stored in the failed-job repository before the delivery is rejected; it is never silently acknowledged.

Verifying It

A new QueueServiceProviderUnhandledMessageTest drives the fix through the real database-backed composition — QueueServiceProvider, DbalQueue, DbalTransport, and DatabaseFailedJobRepository — instead of a bare Worker in isolation:

Test	What it proves
`acceptedUnsupportedMessageRetriesThenFailsDurablyInsteadOfBeingAcknowledged`	An unsupported message is released once on the first attempt, then durably failed and recorded on the second — never silently acked
`firstSupportingCustomHandlerExecutesOnceAndAcknowledgesNormally`	A message with a matching handler still runs exactly once and acks normally
`providerJobHandlerStillExecutesVoidJobAndAcknowledgesNormally`	Existing `Job` dispatch through the provider is unaffected

A fourth case, failedRepositoryOutagePreservesUnsupportedDeliveryForLeaseRecovery, goes the other way on purpose: it's added to the existing WorkerTest and wires up a bare Worker with a stub FailedJobRepositoryInterface that throws on record() — not something you can provoke on demand through the real DatabaseFailedJobRepository. That's the test that would have caught a version of this fix that traded "silently ack an unhandled message" for "silently lose it if the failed-job store is unavailable": when the stub throws, the delivery stays in_progress for lease recovery instead of vanishing a second way.

Both files pass alongside the rest of the suite. The queue package's unit and contract tests ran at 236 tests, 629 assertions after the change — the provider-composition cases alone account for 3 tests and 40 assertions, the outage control for 1 test and 5 assertions.

The General Lesson

A dispatch loop that runs out of candidates without doing anything is easy to write and easy to miss, because "no handler matched" doesn't read like an error — it reads like the absence of work. But a message pulled off a durable queue was never optional work; it's a promise made to whoever dispatched it. If your dispatch loop can finish without ever calling a handler, and the caller can't tell that apart from a real success, you don't have a queue — you have a way to accept work and then forget it happened. The fix here was one throw statement. What made it correct was that it plugged into retry, backoff, and dead-letter paths that already existed, instead of inventing a bespoke error path for one more corner case.

Baamaapii

Fixing a cache:clear command that couldn't run and couldn't be trusted

Russell Jones — Mon, 14 Sep 2026 12:21:51 +0000

Ahnii!

Waaseyaa's cache:clear CLI command had two bugs stacked on top of each other: it couldn't be constructed by the real CLI at all, and once that was worked around, it cleared a hardcoded list of bins that didn't match what the application actually configured. Here's both bugs, the fix, and why a command that prints "cleared" needs to be checked against real state, not just its own exit code.

The Bug: A Command That Couldn't Run, Then Lied When It Could

The first problem was structural. CacheFactoryInterface had no binding anywhere in the CLI's ConsoleKernel boot path — only HttpKernel::finalizeBoot() ever built a CacheFactory. Every real invocation of cache:clear failed before it could do anything:

No binding for Waaseyaa\Cache\CacheFactoryInterface in KernelHandlerContainer

The second problem was hiding behind the first. Once constructible, the handler cleared a fixed list of bin names:

final class CacheClearHandler
{
    private const array DEFAULT_BINS = ['default', 'render', 'discovery', 'config'];

    public function __construct(
        private readonly CacheFactoryInterface $cacheFactory,
    ) {}

    public function execute(SymfonyCommandIO $io): int
    {
        // ...
        foreach (self::DEFAULT_BINS as $binName) {
            $this->cacheFactory->get($binName)->deleteAll();
        }

        $io->writeln('All cache bins cleared.');

        return 0;
    }
}

That list had drifted from what the application actually registers: render, discovery, and mcp_read. Two things followed from the mismatch:

mcp_read was unreachable. It was never in DEFAULT_BINS, so cache:clear never touched it, no matter what you asked for.
default and config printed "cleared" for nothing. CacheFactory::get() hands back a usable backend for any bin name, configured or not — a fresh, empty, unconfigured fallback. Clearing it "succeeds," but there was never any real data behind that name. The command reported success for two bins that didn't exist and silently skipped the one that did.

The exit code was 0 whether the bin was real or not. That's what makes this worse than an outright crash — a crash gets noticed; a wrong success message doesn't.

The Fix: One Canonical List, Shared by HTTP and CLI

The fix starts with a single accessor for "what bins does this configuration actually register":

final class CacheConfiguration
{
    // ...

    public function getConfiguredBins(): array
    {
        $bins = [];
        foreach (array_keys($this->binMapping) as $bin) {
            $bins[$bin] = true;
        }
        foreach (array_keys($this->binFactories) as $bin) {
            $bins[$bin] = true;
        }

        // PHP coerces a numeric-string array key to int, so array_keys() would
        // hand back int(123) for a bin registered as '123' -- violating the
        // declared list<string> and making the consumer report a configured
        // bin as "not configured". Cast back to the registered string form.
        return array_map(strval(...), array_keys($bins));
    }
}

AbstractKernel::buildCacheFactory() becomes the one place the framework's production bins (render, discovery, mcp_read) get composed:

public function buildCacheFactory(RuntimeEpochInterface $runtimeEpoch): CacheFactory
{
    $providerFactory = $this->providerCacheFactory();
    if ($providerFactory !== null) {
        return $providerFactory;
    }

    // ... derive $pdo, $cacheHmacKey, $projectionDiagnostic ...

    $cacheConfig = new CacheConfiguration();
    $cacheConfig->setFactoryForBin('render', fn(): DatabaseBackend => new DatabaseBackend(
        $pdo, 'cache_render', hmacKey: $cacheHmacKey, projectionDiagnostic: $projectionDiagnostic,
    ));
    $cacheConfig->setFactoryForBin('discovery', fn(): DatabaseBackend => new DatabaseBackend(
        $pdo, 'cache_discovery', hmacKey: $cacheHmacKey, projectionDiagnostic: $projectionDiagnostic,
    ));
    $cacheConfig->setFactoryForBin('mcp_read', fn(): RuntimeEpochCacheBackend => new RuntimeEpochCacheBackend(
        new DatabaseBackend($pdo, 'cache_mcp_read', hmacKey: $cacheHmacKey, projectionDiagnostic: $projectionDiagnostic),
        $runtimeEpoch->fingerprint(),
    ));

    return $this->cacheFactory = new CacheFactory($cacheConfig, $projectionDiagnostic);
}

HttpKernel::finalizeBoot() now calls that method instead of building its own CacheConfiguration inline, and the CLI's handler container gains bindings for both CacheFactoryInterface and CacheConfiguration that go through the same method. HTTP-serving boot and the CLI can no longer register a different set of bins from each other — which also fixes the original "no binding" failure, since the CLI now has one.

With a real, shared list to enumerate, CacheClearHandler stops hardcoding anything:

private function clearConfigured(SymfonyCommandIO $io): int
{
    $bins = $this->cacheConfiguration->getConfiguredBins();

    if ($bins === []) {
        $io->writeln('No cache bins are configured.');

        return 0;
    }

    $cleared = [];
    $failed = [];

    foreach ($bins as $binName) {
        try {
            $this->cacheFactory->get($binName)->deleteAll();
        } catch (\Throwable $e) {
            $io->writeln(sprintf('Cache bin "%s" failed to clear: %s', $binName, $e->getMessage()));
            $failed[] = $binName;
            continue;
        }

        $io->writeln(sprintf('Cache bin "%s" cleared.', $binName));
        $cleared[] = $binName;
    }

    if ($failed === []) {
        $io->writeln('All cache bins cleared.');

        return 0;
    }

    if ($cleared === []) {
        $io->writeln('No cache bins were cleared.');

        return 1;
    }

    $io->writeln(sprintf(
        'Partially cleared: %d of %d cache bins failed (%s).',
        count($failed),
        count($bins),
        implode(', ', $failed),
    ));

    return 1;
}

A few behavior changes fall out of this that are worth calling out:

One failing bin no longer aborts the rest. Each bin is attempted independently, and the exit status reflects total success, total failure, or partial failure — never a blanket "All cache bins cleared." when that isn't true.
--bin naming an unconfigured bin is now a reported failure, not a false success. clearOne() checks getConfiguredBins() first and exits 1 with "nothing to clear" instead of quietly clearing an empty fallback backend.
--bin/--tags option shapes are unchanged. This was a bin-inventory and reporting fix, not a CLI interface change.

The fix doesn't claim this ever caused a production stale-read incident. mcp_read is namespaced by a runtime epoch fingerprint, so prior-epoch entries were already unreadable regardless of cache:clear. What it fixes is narrower and still worth fixing: the command couldn't run, and once it could, its success message wasn't describing reality.

Verifying It

The existing test suite mocked a factory and asserted deleteAll() was called four times. That assertion holds regardless of which four bin names were actually used, so it couldn't have caught the mismatch. The new tests assert against real backend state through the actual registered command:

Test	What it proves
`clearsAllConfiguredBins`	Only the bins a `CacheConfiguration` actually registers get cleared
`noConfiguredBinsReportsNothingToClear`	An empty configuration reports "No cache bins are configured," never a false success
`explicitUnconfiguredBinIsNotReportedAsCleared`	`--bin nonexistent` exits 1 with "nothing to clear," never "cleared"
`backendThatThrowsIsReportedAsFailureWithoutAbortingOtherBins`	One bin throwing still lets the others clear, with a truthful partial-failure message and exit code
`allBinsThrowingIsTotalFailure`	Every bin failing reports "No cache bins were cleared," not "All cache bins cleared."

Two of the discriminating cases drive the real registered cache:clear command through the production KernelHandlerContainer, with a real CacheFactory/CacheConfiguration and a DatabaseBackend over SQLite — checking actual table state before and after, not just stdout.

The General Lesson

A command that hardcodes "the list of things to process" instead of asking the configuration what it actually registers will drift the first time someone adds or renames a bin elsewhere in the codebase. Drift alone isn't the scary part. What's scary is that $factory->get($name) doesn't fail for an unconfigured name — it hands back an empty fallback backend, so the command keeps reporting success on names that no longer mean anything. A test suite that mocks deleteAll() and counts calls can't tell the difference: it passes against the correct list of bins and the wrong one alike. If "cleared" can be true for a bin that was never real, the tests have to check actual backend state, not call counts. That check is worth more than removing DEFAULT_BINS itself.

Baamaapii

A loopback-only proxy for prototyping northway's feed reader

Russell Jones — Mon, 14 Sep 2026 12:21:47 +0000

Ahnii!

northway is a Go service that turns approved sources into small, ranked, source-backed news feeds for AI agents, deployed Pi-first. Before committing that UX to the single-process Go build, I prototyped it in the browser first — a plain HTML/CSS/JS reader backed by a small Node.js proxy. What follows is why that prototype needed its own proxy, and the checks that keep it from becoming anything more than a local UX reference.

Why a proxy, and why disposable

The prototype had one job: settle the reader's interaction design before any of it went into the Go service. That meant nailing down:

Five feed tabs — Mixed, Development, Entertainment, Canada, World
A compact dark layout
Honest handling of empty or failed results

Doing that in a browser means calling northway's real API from client-side code, and that creates an immediate problem: the API key can't go anywhere client-side JavaScript can read it.

The fix is a small node:http server (prototype/server.mjs) that serves the static files and exposes one endpoint, /api/news, which holds the key and forwards requests upstream:

const apiKey = process.env.NORTHWAY_API_KEY;

const upstream = await fetch(`${northwayURL}/v1/feed-queries`, {
  method: "POST",
  signal: AbortSignal.timeout(10_000),
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    feed_id: selected.id,
    context: { intent: selected.context, technologies: [], focus: [selected.label] },
    max_age_hours: maxAgeHours,
    limit: 10,
  }),
});

The browser only ever talks to /api/news on the same origin. It never sees the key, the upstream URL, or the feed ID mapping — those live entirely on the proxy side. The Idempotency-Key and a 10-second AbortSignal.timeout guard against duplicate or hung upstream calls, which matters when every query is a paid AI-provider request.

Refuse to bind anywhere but loopback

A proxy that holds a live API key is a liability the moment it's reachable from anything but the machine running it. The server checks its own bind address before it does anything else:

const host = process.env.HOST ?? "127.0.0.1";
if (!["127.0.0.1", "localhost", "::1"].includes(host)) {
  throw new Error("HOST must be a loopback address; this prototype cannot be exposed.");
}

There's no flag to override this — the only way past the check is to not pass a non-loopback HOST in the first place. The README spells out the same constraint in plain language: keep it bound to loopback, don't put it on a LAN, don't expose it to the internet.

Don't trust requests just because they're local

Loopback-only isn't a substitute for validating what shows up on /api/news. The handler rejects anything that doesn't look like the reader's own frontend before routing even happens:

Check	Rejects when	Response
Host header	Doesn't match `127.0.0.1:<port>`, `localhost:<port>`, or `[::1]:<port>`	400
Content-Type	Anything other than `application/json`	415
`Sec-Fetch-Site`	Present and not `same-origin` (blocks other tabs and pages)	403
Body size	Over 16 KB	Aborted, never buffered

Every response also carries a restrictive Content-Security-Policy (default-src 'self', locked-down script-src/style-src, no inline scripts or styles), X-Content-Type-Options: nosniff, and Referrer-Policy: no-referrer. None of it is exotic, but skipping any row in that table turns "only my machine can reach this" into "anything on my machine can reach this."

Preserve the last good feed on failure

On the client side, a failed refresh shouldn't blank out a working feed. app.js tracks whether a snapshot has ever loaded successfully and falls back to it on error instead of clearing the screen:

} catch (error) {
  if (requestNumber !== activeRequest) return;
  if (error.name === "AbortError") return;
  activeFeed = displayedFeed;
  selectFeed(displayedFeed);
  briefingHeading.textContent = feedLabels[displayedFeed];
  briefingMeta.textContent = hasSnapshot
    ? `Refresh failed · showing last available ${feedLabels[displayedFeed]} feed`
    : "Service unavailable";
  ...
}

An activeRequest counter also discards any response that isn't from the most recent fetch, so clicking between tabs quickly can't let a slow, stale response overwrite a newer one. When a feed genuinely comes back empty, the reader says so directly ("No current stories matched this feed") rather than padding the list. That's the same rule spelled out in app.js itself: the empty result is preserved rather than padded.

What's next

This prototype has clear limits:

It doesn't deploy northway
It doesn't poll unattended
It isn't the Pi runtime — it's explicitly excluded from the production Go image

Its only job was to prove out the interaction design against real, live snapshots (all five feeds, desktop and mobile), so the accepted UX could guide a single-process Go implementation instead of being designed twice.

Baamaapii

Fixing a schema-mutating access check in Waaseyaa's taxonomy package

Russell Jones — Thu, 10 Sep 2026 11:40:38 +0000

Ahnii!

Waaseyaa's packages/taxonomy package manages vocabularies and terms, with a foreign key tying every term row back to the vocabulary it belongs to. Two places in that package called the same "make sure this foreign key exists" helper unconditionally, and one of them ran on every delete-access check against a vocabulary — meaning ordinary request traffic could issue an ALTER TABLE under load. Here's the bug, the fix, and why "no DDL on the request path" needs to be a contract, not just a habit.

The Bug: DDL Behind an Access Check

TaxonomyServiceProvider::boot() and VocabularyAccessPolicy::access() both called VocabularyReferenceConstraint::ensure() unconditionally. ensure() issues DDL: it adds the taxonomy_term → taxonomy_vocabulary foreign key if it's missing.

Calling that from boot() is already risky — a production deployment whose schema hadn't finished a coordinated sync yet could have a request trigger the ALTER TABLE under live traffic. But the call inside VocabularyAccessPolicy::access() was worse, because it wasn't bounded to boot at all. It ran on every delete-access check against a vocabulary, for the lifetime of the process:

public function access(EntityInterface $entity, string $operation, AccountInterface $account): AccessResultInterface
{
    if ($operation !== 'delete') {
        return AccessResult::neutral();
    }

    if ($this->database !== null) {
        new VocabularyReferenceConstraint($this->database)->ensure();
    }

    $terms = $this->entityTypeManager->getRepository('taxonomy_term')->findBy(
        ['vid' => (string) $entity->id()],
        limit: 1,
    );
    // ...
}

An access policy's job is to answer "is this delete allowed," not to mutate the schema on the way to answering. The framework had already closed this exact class of defect once, in AttachmentServiceProvider (issue #2478) — this was the same mistake resurfacing in a package that hadn't been through that fix.

The Fix: DDL Belongs Only to Coordinated Schema Sync

Both unconditional ensure() calls were removed (issue #2761). VocabularyAccessPolicy no longer accepts a database at all — its existing findBy() check (does any term still reference this vocabulary?) is the real enforcement. The foreign key becomes a storage-level backstop, installed exclusively by coordinated schema sync (db:init, schema:sync):

final class VocabularyAccessPolicy implements AccessPolicyInterface
{
    public function __construct(
        private readonly EntityTypeManagerInterface $entityTypeManager,
    ) {}

    public function access(EntityInterface $entity, string $operation, AccountInterface $account): AccessResultInterface
    {
        if ($operation !== 'delete') {
            return AccessResult::neutral();
        }

        $terms = $this->entityTypeManager->getRepository('taxonomy_term')->findBy(
            ['vid' => (string) $entity->id()],
            limit: 1,
        );
        // ...
    }
}

No new migration was needed for the sync path — the entity type already declares its _foreignKeys, and SqlSchemaHandler's generic ensureDeclaredForeignKeys() (used by every entity type with declared foreign keys) picks it up automatically once the unconditional call in boot() is gone.

TaxonomyServiceProvider::boot() keeps a local/development-only convenience materialization, gated the same way AttachmentServiceProvider gates its own schema convenience:

public function boot(): void
{
    // ... event listener wiring unchanged ...

    $database = $this->resolveOptional(DatabaseInterface::class);
    if ($database instanceof DatabaseInterface && $this->allowsConvenientSchemaMaterialization()) {
        new VocabularyReferenceConstraint($database)->ensure();
    }
}

private function allowsConvenientSchemaMaterialization(): bool
{
    return RuntimePolicy::resolve($this->config)->isDevelopment();
}

Production and staging boot no longer touch the foreign key at all, and neither does any request that reaches the access policy.

Closing the "Silent Skip" Gap

Removing the DDL calls raises an obvious question: what happens in production if the foreign key is genuinely missing — say, a deploy where schema sync hasn't run yet? Silently skipping the constraint would be its own bug. The framework already had a no-DDL runtime contract, SqlSchemaHandler::assertRuntimeSchema(), which every getRepository() resolution runs and which already asserted declared unique keys were present. It now asserts declared foreign keys too:

private function assertDeclaredForeignKeysReady(): void
{
    if (!$this->entityType instanceof EntityTypeForeignKeyDefinitionInterface) {
        return;
    }
    $schema = $this->database->schema();
    if (!$schema instanceof ForeignKeySchemaInterface) {
        return;
    }

    foreach ($this->entityType->getStorageForeignKeys() as $definition) {
        if (!$schema->tableExists($definition['table'])) {
            continue;
        }
        if ($schema->foreignKeyExists($this->tableName, $definition['name'])) {
            continue;
        }
        throw new \RuntimeException(sprintf(
            '[S1-DB106] Required runtime schema is unavailable for table "%s"; missing: foreign key %s. Apply migration "waaseyaa schema:sync" through the schema coordinator.',
            $this->tableName,
            $definition['name'],
        ));
    }
}

That required a new read-only capability: ForeignKeySchemaInterface already had addForeignKey() (DDL) but nothing to check whether a key already exists without mutating anything. A foreignKeyExists() companion method was added to the interface — contract-only, since the concrete DBALSchema implementation already had the underlying check available.

A declared key whose referenced table doesn't exist yet is skipped rather than treated as an error, because entity type registration order isn't guaranteed (taxonomy_term registers before taxonomy_vocabulary) — that table's own readiness is a separate concern.

Verifying It

The risk with a "read-only" schema check is that it quietly isn't, on some database platform. That got its own test, proving foreignKeyExists() and tableExists() never call executeStatement() — using mocked DBAL connections that report MySQL, PostgreSQL, and SQLite platforms, the same technique the existing DDL-generation tests already used for portability:

Check	What it proves
`foreignKeyExistsIsReadOnlyOnRealSqlite`	Real SQLite in-memory database: false before creating the key, true after
`foreignKeyExistsNeverIssuesDdlAndReportsAbsence`	MySQL, PostgreSQL, SQLite: reports `false`, never calls `executeStatement()`
`foreignKeyExistsNeverIssuesDdlAndReportsPresence`	Same three platforms: reports `true`, never calls `executeStatement()`
`tableExistsNeverIssuesDdl`	Same guarantee for the existing `tableExists()` check

On the assertRuntimeSchema() side, new unit tests cover a table materialized without its declared foreign key, proving the assertion throws with the [S1-DB106] message instead of silently passing. There's no live MySQL or PostgreSQL server in this environment, so the mocked-connection tests are what stand in for cross-platform proof; real fresh-install and concurrent-upgrade behavior against live servers is explicitly called out as deferred.

The General Lesson

"No DDL on the request path" sounds obvious once you say it. It's easy to violate by accident anyway, because DDL doesn't announce itself — ensure() reads like a harmless idempotent helper, not a schema mutation. The tell was where the call lived. A boot() method is at least bounded to process startup; an access-check method runs on every matching request for as long as the process is up. So anywhere your code "makes sure X exists" as a side effect of answering an unrelated question, ask whether that assurance is DDL — and if it is, ask who's actually allowed to run it. The fix here wasn't just deleting the two bad calls. It was making the runtime assert the schema is already correct and fail loudly if it isn't, so removing the convenience path couldn't quietly turn into a silent skip.

Baamaapii

Stop walking the filesystem in your CI gates — ask git instead

Russell Jones — Wed, 09 Sep 2026 14:23:54 +0000

Ahnii!

Waaseyaa has a family of "S1 roster" gate scripts that scan the tree for specific governed patterns — raw SQLite construction, schema-boundary crossings — and compare what they find against a recorded, reviewed roster. A related check-access-hardening gate scans for missing authorization guards. All of them needed the same thing first: a list of files to scan. Getting that list right turned out to be harder than it sounds, and the eventual fix replaced a hand-maintained exclusion list with one line: ask git.

The problem with walking the filesystem

The original scanners enumerated files with a RecursiveDirectoryIterator and then subtracted paths that matched a denylist — vendor/, node_modules/, .git/, and so on. That denylist was a stand-in for "repository content," rebuilt by hand instead of asked from the one tool that actually knows the answer. Every time a new kind of untracked tree showed up, the denylist needed another entry.

That's exactly what happened. Nested git worktrees under .worktrees/ or .claude/worktrees/, and a populated packages/<pkg>/vendor/, weren't on the list. On the primary checkout, that gap produced:

24,780 phantom findings across three gates — 18,844, 5,932, and 4 — as nested worktree build caches and vendored trees read as governed pattern matches.
--write-construction-roster would have committed .worktrees/... paths into the tracked roster, permanently baking a developer-local artifact into shared state.
check-access-hardening had no exclusion at all beyond requiring /src/ in the path, so a vendored library shipping its own src/ directory was scanned as if it were first-party code — the source of that gate's 4.

The root cause wasn't any single missing entry — it was structural. A walk-minus-denylist re-creates the repository boundary by hand, and a denylist only ever grows in response to the last thing that broke it.

The fix: `git ls-files`, not a walk

Both scanners now go through one shared helper, bin/lib/repository-files.php:

function repositoryFiles(string $root, array $pathspecs = []): array
{
    $normalizedRoot = rtrim(str_replace('\\', '/', $root), '/');
    $arguments = ['ls-files', '-z', '--cached', '--others', '--exclude-standard'];
    $pathspecs = array_values(array_filter($pathspecs, static fn(string $pathspec): bool => $pathspec !== ''));
    if ($pathspecs !== []) {
        $arguments[] = '--';
        array_push($arguments, ...$pathspecs);
    }

    [$exitCode, $listing, $error] = repositoryGit($normalizedRoot, $arguments);
    if ($exitCode !== 0) {
        throw new RuntimeException(sprintf(
            'repository-files: git could not enumerate repository files under %s (exit %d)%s',
            $normalizedRoot,
            $exitCode,
            $error === '' ? '.' : ': ' . $error,
        ));
    }

    $files = [];
    foreach (explode("\0", $listing) as $relative) {
        if ($relative === '' || !is_file($normalizedRoot . '/' . $relative)) {
            continue;
        }
        $files[$relative] = true;
    }
    $paths = array_keys($files);
    sort($paths, SORT_STRING);

    return $paths;
}

git ls-files --cached --others --exclude-standard returns tracked files plus untracked files git would add, honoring .gitignore along the way. That single command replaces the denylist entirely:

.gitignore becomes the exclusion boundary by construction. Nothing to maintain, nothing to forget.
Git never descends into another repository's work tree, so a nested worktree is invisible whether or not it happens to be ignored. No .worktrees/ special case needed.
A root git can't enumerate fails closed — repositoryFiles() throws instead of silently falling back to a filesystem walk. If the gate can't trust its own file list, it doesn't run.

The second bug: git answered the wrong repository's question

Shipping the git-native scanner exposed a subtler problem. A pre-push hook run from a linked worktree exports GIT_DIR=<main>/.git/worktrees/<name> into the environment. The scanner's git -C $root ls-files inherited that variable — and GIT_DIR overrides -C entirely, so the command enumerated the hook's repository instead of the scan root.

Worse, the access-hardening gate's self-test calls git init on a fixture directory to set up test data. With GIT_DIR still pointing at the developer's own worktree gitdir, that git init "reinitialized" the developer's real repository as bare (core.bare=true in the shared .git/config), breaking every git command in the main checkout. Any contributor with project hooks installed who pushed from .claude/worktrees/* or .worktrees/* could hit this.

The fix scrubs every environment variable git itself uses to select a repository before running a child process:

const REPOSITORY_LOCAL_GIT_ENVIRONMENT = [
    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
    'GIT_COMMON_DIR',
    'GIT_CONFIG',
    'GIT_CONFIG_COUNT',
    'GIT_CONFIG_PARAMETERS',
    'GIT_DIR',
    'GIT_GRAFT_FILE',
    'GIT_IMPLICIT_WORK_TREE',
    'GIT_INDEX_FILE',
    'GIT_NO_REPLACE_OBJECTS',
    'GIT_OBJECT_DIRECTORY',
    'GIT_PREFIX',
    'GIT_REPLACE_REF_BASE',
    'GIT_SHALLOW_FILE',
    'GIT_WORK_TREE',
];

function repositoryGitEnvironment(): array
{
    $environment = getenv();
    foreach (REPOSITORY_LOCAL_GIT_ENVIRONMENT as $name) {
        unset($environment[$name]);
    }

    return $environment;
}

This is git's own local_repo_env list — the set git clears before running a command against another repository. With it scrubbed, -C $root is the only thing left that selects which repository a child git process operates on.

What changed, and what didn't

Before	After
`RecursiveDirectoryIterator` + hand-maintained denylist	`git ls-files -z --cached --others --exclude-standard`
New untracked-tree kind → new denylist entry, reactively	`.gitignore` is the boundary; nothing to add
Access-hardening gate: no exclusion beyond an `/src/` path check	Same git-backed enumeration as the roster scanners
Git child processes inherited hook environment	Repository-selecting env vars scrubbed on every git call
Silent fallback risk if enumeration failed	Fails closed with a clear error; no fallback walk

Regenerating all four support/s1-*-roster.json files against the new scanner produced a zero diff — the fix removed phantom candidates without touching a single legitimate one. All three gates then passed read-only against a checkout holding sixteen nested worktrees and a populated packages/ai-agent/vendor/.

The general lesson

If you're writing a script that scans "the repository" — a linter, a gate, an audit tool — resist the urge to walk the filesystem and subtract what you don't want. A denylist encodes everything you've already been burned by; it says nothing about what you haven't hit yet. Git already knows the answer to "what files are in this repository," .gitignore and all, and git ls-files will give it to you in one call.

And if that script ever shells out to git from inside a hook or a nested worktree, don't assume the environment is clean. Hooks can carry repository-selecting variables that override the very -C flag you're relying on to scope the command — scrub them, or you may find git init pointed at the wrong repository entirely.

Baamaapii

Stop letting a failing audit logger crash requests that already succeeded

Russell Jones — Wed, 09 Sep 2026 14:23:51 +0000

Ahnii!

Waaseyaa's MCP endpoint writes a durable audit record around every tool call: a reservation before the tool runs, a terminal record after. That ledger is deliberately fail-closed — if it can't record a write attempt, the write is refused. But the code path that reports a ledger failure to the application logger had the opposite problem: it was fail-open in the worst way. If the logger itself threw, the throw escaped uncaught, after the real outcome had already been decided. Here's the bug, the fix, and the worse variant of the same gap one layer up.

The bug: a logger call with no safety net

AuditedToolDispatcher::finalizeQuietly() runs after a tool has already executed. It tries to write the terminal audit record, and if that write fails, it reports the failure — but the report itself wasn't guarded:

private function finalizeQuietly(StrictAuditReceipt $receipt, AuditStage $stage, string $toolName): void
{
    try {
        $this->ledger->finalize($receipt, $stage, $this->metadata);
    } catch (\Throwable $e) {
        $this->reportAuditFailure('agent_tool.audit_finalize_failed', [
            'correlation_id' => $this->correlationId,
            'surface' => $this->surface,
            'receipt_id' => $receipt->id,
            'tool' => $toolName,
            'stage' => $stage->value,
            'exception' => $e::class,
            'note' => 'Dangling reservation: outcome unknown, side effect may have committed.',
        ]);
    }
}

Before the fix, reportAuditFailure() called $this->logger?->critical(...) directly. If the logger itself threw — a broken handler, a full disk, a downed log shipper — that critical() call escaped dispatch() as an uncaught exception, even though the tool had already run and its side effect had already committed. The caller would see a crash instead of the completed result, and a naive retry would repeat an action that already happened.

Two sibling call sites in the same class — agent_tool.audit_reservation_failed and agent_tool.audit_terminal_record_failed — had the identical unguarded shape. All three report an outcome that is already final; none of them should be able to overturn it.

The fix: swallow the logger's own failures

The fix wraps every one of those report sites in a private helper that catches and discards:

private function reportAuditFailure(string $event, array $context): void
{
    try {
        $this->logger?->critical($event, $context);
    } catch (\Throwable) {
        // Deliberately empty — see method doc.
    }
}

The empty catch is intentional, not an oversight. The method's docblock spells out why the failure isn't re-logged: there's no framework LoggerInterface convention for logging a logging failure, recursing into a broken sink risks looping, and error_log() is reserved for the logging infrastructure itself rather than its callers. A logging failure must never be allowed to replace a caller-visible outcome with an unrelated crash — so the safest thing the helper can do is nothing.

The same gap, one layer up — with a worse ordering problem

McpEndpoint (the layer above AuditedToolDispatcher) dispatches tools/call directly, so nothing downstream catches for it. It carried the identical unguarded logger call at its own post-execution finalize path — meaning a throwing logger there became an HTTP transport failure for a write that had already committed. McpEndpoint got its own reportAuditFailure(), deliberately duplicated rather than shared: mcp is Layer 6 and ai-tools is Layer 5 in Waaseyaa's layering, and a containment detail doesn't justify a new cross-package public symbol.

A follow-up sweep found six more unguarded sites in McpEndpoint, all at error() level rather than critical():

the rate-limiter durability check
the protocol dispatch path
the resource dispatch path
the malformed-response branches

Those got a sibling helper:

private function reportOperationalFailure(string $event, array $context): void
{
    try {
        $this->logger?->error($event, $context);
    } catch (\Throwable) {
        // Deliberately empty — see method doc.
    }
}

This family turned out to have a worse failure mode than the audit-critical one, even though it guards no committed side effect. Four of its six call sites report before their own auditTerminal() call:

try {
    $response = $handler();
} catch (\Throwable $e) {
    $this->reportOperationalFailure('mcp.protocol_execution_failed', [
        'correlation_id' => $correlationId,
        'method' => $method,
        'exception' => $e::class,
    ]);

    $this->auditTerminal(
        AuditStage::ExecutionFailed,
        $correlationId,
        $actorUid,
        $method,
        $method,
        [],
        ['reason' => 'protocol_handler_threw', 'exception' => $e::class],
    );
    // ...
}

An unguarded throw at reportOperationalFailure() here wouldn't just crash the request — it would also skip the auditTerminal() call three lines below, silently erasing the terminal audit record for a request that already failed. That's a strictly worse outcome than the reportAuditFailure() gap, where the reported outcome is always already decided and recorded.

What changed

Site	Level	Reports relative to outcome	Guard added
`AuditedToolDispatcher` reservation/terminal/finalize	`critical`	After outcome is final	`reportAuditFailure()`
`McpEndpoint` reservation/finalize/approval paths	`critical`	After outcome is final	`reportAuditFailure()` (duplicated per layer)
`McpEndpoint` rate limiter, protocol/resource dispatch, malformed response	`error`	4 of 6 before `auditTerminal()`	`reportOperationalFailure()`

How it was tested

Both fixes came with a ThrowingLogger test double driven through the real request boundary — dispatch() for the ai-tools side, serve() for MCP — not by calling the private helpers directly. Each test followed the same discipline:

Red first. Verified against the unmodified code, failing at the exact line the throw would have escaped from.
Green after. Re-run once the guard was added.
Two assertions per error()-level site. For the four sites that precede their own auditTerminal() call, each test checks that the request still completes and that the terminal audit record still gets written despite the broken logger.
Reflection for the unreachable branches. Two malformed-response branches can't be hit through any conforming handler, so those are driven directly on the private methods via reflection.

The general lesson

Audit and observability code that runs after a decision has already been made must never be allowed to overturn that decision. If a logging call inside a catch block can throw, and nothing catches that throw, your logger has quietly become a second failure mode for every code path that touches it — one your test suite may never exercise, because tests almost always run against a logger that works. The fix isn't clever: catch \Throwable around the logging call itself, swallow it, and don't try to log the failure to log. But you have to go looking for every site with that shape, because a refactor can reintroduce an unguarded one without any test noticing — unless you specifically test with a logger that fails.

Baamaapii

Fixing a silent truncation bug in Waaseyaa's StreamHttpClient

Russell Jones — Mon, 07 Sep 2026 12:28:25 +0000

Ahnii!

Waaseyaa's packages/http-client package wraps PHP streams behind a small HttpClientInterface, with StreamHttpClient as the production implementation. It caps how many bytes of a response body it will read, so a runaway or hostile endpoint can't exhaust worker memory. That cap had a bug: hitting it didn't fail the request. It silently handed back a truncated body as a successful HttpResponse. What follows walks through the bug, the fix, and the broader lesson about bounding a read without lying about what you actually read.

The Bug: A Byte Ceiling That Didn't Fail

The original fetch() method read the body with a single call:

// m4: cap the body so a runaway/hostile endpoint can't OOM the worker.
$responseBody = @stream_get_contents($handle, $this->maxResponseBytes);

if ($responseBody === false) {
    throw $this->transportFailure($method, $url);
}

return $responseBody;

stream_get_contents() with a length argument stops reading once it hits that many bytes and returns whatever it has. It doesn't return false just because the stream had more data waiting — an endpoint returning a body larger than maxResponseBytes produced a 200 OK with a truncated prefix instead of an error. The caller had no way to know the body was incomplete unless it happened to check the length itself.

The Fix: Fail Closed, Not Silent

The fix, tracked as FW-HTTP-STREAM-TRUNCATION-01, replaces the single stream_get_contents() call with a loop that reads in chunks and checks completeness against what the response actually declared:

Over-limit bodies throw. If the body would exceed maxResponseBytes, the client throws a typed HttpRequestException instead of returning a partial string.
Content-Length mismatches throw. If the connection closes (or times out) before the declared length is reached, that's a failure, not a short success.
A declared length above the ceiling is rejected before reading starts, so memory stays bounded even for a body the client will never accept.
Exact-limit bodies still succeed. A body whose size equals maxResponseBytes exactly, including chunked and connection-close bodies with no Content-Length at all, is a valid, complete response.

private function readCompleteBody($handle, string $method, string $url): string
{
    $headers = http_get_last_response_headers() ?? [];
    $status = $this->parseStatusCode($headers);
    // HEAD and these status codes carry metadata, never a response body.
    if (strtoupper($method) === 'HEAD' || ($status >= 100 && $status < 200) || $status === 204 || $status === 304) {
        return '';
    }
    $contentLength = $this->headerContentLength($headers);
    if ($contentLength !== null && $contentLength > $this->maxResponseBytes) {
        throw $this->boundedBodyFailure($method, $url, 'HTTP response body exceeded the configured maximum');
    }

    $body = '';
    while (!feof($handle)) {
        $remaining = $this->maxResponseBytes - strlen($body);
        if ($contentLength !== null && strlen($body) === $contentLength) {
            break;
        }
        $readBytes = $contentLength !== null ? $contentLength - strlen($body) : $remaining + 1;
        $chunk = @fread($handle, max(1, min(8192, $readBytes)));
        $meta = stream_get_meta_data($handle);
        if ($meta['timed_out'] === true) {
            throw $this->boundedBodyFailure($method, $url, 'HTTP response body was incomplete');
        }
        if ($chunk === false) {
            throw $this->transportFailure($method, $url);
        }
        if ($chunk === '') {
            break;
        }
        $body .= $chunk;
        if (strlen($body) > $this->maxResponseBytes) {
            throw $this->boundedBodyFailure($method, $url, 'HTTP response body exceeded the configured maximum');
        }
    }

    if ($contentLength !== null && strlen($body) !== $contentLength) {
        throw $this->boundedBodyFailure($method, $url, 'HTTP response body was incomplete');
    }

    return $body;
}

Reading one extra byte beyond maxResponseBytes when there's no declared Content-Length is what turns "we stopped because we're at the limit" into "we detected the body actually exceeds the limit." Without that extra byte, an exact-limit body and an over-limit body look identical.

A stream_set_timeout() call was also added before the read loop. A connection that stalls mid-body now times out and fails closed instead of hanging or silently truncating.

Where the Framing Boundary Actually Sits

Part of getting this right is knowing which responses have no body at all, regardless of what their headers claim:

Response	Body
`HEAD` request	none
`1xx` status	none
`204 No Content`	none
`304 Not Modified`	none
Declared `Content-Length`	stops exactly at that length, doesn't wait for connection close
No `Content-Length` (connection-close framing)	EOF defines completion

The change record is honest about the limits of this fix, too. PHP's HTTP stream wrapper dechunks Transfer-Encoding: chunked responses and strips the header before the client ever sees the stream, so the byte ceiling still applies to the decoded body. But StreamHttpClient can't independently verify a missing chunk terminator — that's a problem for PHP's stream layer, not this client. Scoping the fix to what the client can actually observe, and documenting what it can't, beats pretending it covers every framing edge case.

Verifying It

packages/http-client/tests/Unit/StreamHttpClientTransportTest.php covers the cases that matter:

Bodies below, at, and above the limit
Chunked transfer
Absent Content-Length
Mismatched Content-Length
A mid-body timeout
An over-limit 5xx
A complete 404

The suite also gained a small raw HTTP test server (tests/Support/RawHttpServer.php), so these cases could be driven against real socket behavior instead of mocked streams.

The General Lesson

Bounding a read and detecting truncation are two different problems, and it's easy to solve only the first one. stream_get_contents($handle, $limit) does exactly what it says: it reads at most $limit bytes and returns them. It was never going to tell you whether that's all the bytes there were. Any time you cap a read for memory safety, whether that's an HTTP body, a file, or a queue message, ask what happens at the boundary: does hitting the cap look identical to a legitimate response that happens to be exactly that size? If your code can't tell those two cases apart, it's not bounding the read — it's lying about it when the answer would be inconvenient.

Baamaapii

DEV Community: Russell Jones

Fixing a metadata collision bug in Waaseyaa's file repository

The Bug: parse_url() Doesn't Know About Stream Wrappers

The Fix: Treat Every Segment After the Scheme as One Flat Path

Problem 1: Upgrading Doesn't Migrate Existing Sidecars

Problem 2: save() Wasn't Atomic

Verifying It

The General Lesson

Configuring identity-only OAuth requests in Waaseyaa

What Over-Asking Looked Like

Additive Configuration, Not a Parameter Bag

Using It

Hardening the Optional Fields

Why This Matters Beyond Waaseyaa

Host-bound session and CSRF cookies in Waaseyaa

The Four Constraints

One Policy, Two Cookies

Rejected at Construction, Not Discovered in the Browser

Malformed Config Is Rejected Too

What Consumers See

Why This Matters Beyond Waaseyaa

Claude Code and Codex skills are directories, not files

What Claude Code actually discovers

What Codex actually discovers

The fix: one renderer, not two

Claude Code vs. Codex, side by side

What this means if you're building similar tooling

Building a conformant stdio MCP server in PHP

Only One Thing May Write to Stdout

Bounding a Read That Has No Natural Limit

The JSON Object/Array Ambiguity

Telling Old Clients From New Ones

Resolving the Interpreter Without Trusting PATH

The General Lesson

Fixing a silent message-drop bug in Waaseyaa's queue worker

The Bug: An Empty Loop Still Counts as Success

The Fix: Throw Instead of Falling Through

Verifying It

The General Lesson

Fixing a cache:clear command that couldn't run and couldn't be trusted

The Bug: A Command That Couldn't Run, Then Lied When It Could

The Fix: One Canonical List, Shared by HTTP and CLI

Verifying It

The General Lesson

A loopback-only proxy for prototyping northway's feed reader

Why a proxy, and why disposable

Refuse to bind anywhere but loopback

Don't trust requests just because they're local

Preserve the last good feed on failure

What's next

Fixing a schema-mutating access check in Waaseyaa's taxonomy package

The Bug: DDL Behind an Access Check

The Fix: DDL Belongs Only to Coordinated Schema Sync

Closing the "Silent Skip" Gap

Verifying It

The General Lesson

Stop walking the filesystem in your CI gates — ask git instead

The problem with walking the filesystem

The fix: git ls-files, not a walk

The second bug: git answered the wrong repository's question

What changed, and what didn't

The general lesson

Stop letting a failing audit logger crash requests that already succeeded

The bug: a logger call with no safety net

The fix: swallow the logger's own failures

The same gap, one layer up — with a worse ordering problem

What changed

How it was tested

The general lesson

Fixing a silent truncation bug in Waaseyaa's StreamHttpClient

The Bug: A Byte Ceiling That Didn't Fail

The Fix: Fail Closed, Not Silent

Where the Framing Boundary Actually Sits

Verifying It

The General Lesson

The Bug: `parse_url()` Doesn't Know About Stream Wrappers

Problem 2: `save()` Wasn't Atomic

The fix: `git ls-files`, not a walk