DEV Community: Russell Jones

Treat content withdrawal as a reversible migration

Russell Jones — Tue, 03 Nov 2026 14:09:20 +0000

Ahnii!

Removing a page from a website is easy. Withdrawing it safely is not.

A real content withdrawal has to change every public surface while preserving the material needed for review, recovery, or migration. This post uses a recent RHT Circle change to show how to treat that work as a reversible migration instead of a deletion.

Define what withdrawal means

Start with an explicit contract. In this case, five managed articles and four static pages had to leave the public site before their material moved elsewhere.

Withdrawal meant all of the following:

Existing public URLs return 404
News lists and community hubs stop linking to the material
Static and generated sitemaps omit the URLs
Search indexing drops the old public chunks during the normal reindex
Managed article bodies remain stored as unpublished records
Original seed files and static templates remain available for migration
No redirect exists until a verified destination is actually live

That last point avoids a common mistake. A planned destination is not a working destination. Redirecting early turns a controlled withdrawal into a broken handoff.

Preserve content, remove publication state

The managed articles were not deleted. Their slugs were added to an explicit unpublishedSlugs() list, and the seeder created them with status: false.

'status' => !in_array(
    $slug,
    ArticleSeedData::unpublishedSlugs(),
    true,
),

This keeps the body and record available while removing anonymous access. It also gives new installations the same state as production instead of letting a fresh seed accidentally republish withdrawn material.

The refresh path needed a second guard. A slug cannot be both withdrawn and eligible for publication refresh. The seeder now skips any unpublished slug, and the test suite asserts that the unpublished and publication-refresh lists do not intersect.

This is the critical invariant:

Re-running installation or seed refresh must not reverse the withdrawal.

Without that rule, the next deployment can quietly undo the change.

Handle managed and static content differently

The site had two kinds of public material:

Content type	Withdrawal action	Preserved evidence
Managed articles	Keep the entity, set it unpublished	Database record, body, revision history, seed source
Static pages	Remove the route from public catalogues	Twig template and Git history

Trying to force both through one mechanism would hide important differences. A managed article has publication state. A static route does not, so the public route registration itself has to disappear.

The static templates stayed in the repository. That makes the withdrawal reversible without leaving the old URLs reachable. It also keeps the material available for a later migration where the destination may use a different content model.

Remove every discovery path

Returning 404 from the old URL is necessary, but it is not enough. A withdrawn page can still appear public if the rest of the site advertises it.

The change removed references from:

Home and news listings
Community cards and accountability hubs
Manually maintained sitemap XML
The application's generated sitemap route list
Contextual links embedded in other content

Search requires separate attention because an index is another copy of the content. The release procedure relies on the normal app:reindex deployment step to remove old page chunks, then calls for production verification that those chunks are gone.

This is why content withdrawal belongs in release planning. Code can remove routes and links, but the deployed search corpus is runtime state that still has to be checked.

Test absence and preservation together

The strongest regression test does not merely ask whether a page disappeared. It proves that the page is unavailable while its source remains intact.

The integration test runs article migration, boots the application, and then checks each withdrawn article:

Exactly one stored record still exists
Its publication status is false
Its body is not empty
Its public URL returns 404

It also requests the home page, news list, community hub, and sitemap, then asserts that none contains a withdrawn path.

The test name calls out repeated seeding because idempotency is the real risk. A one-time successful withdrawal is not enough. The same release operations must keep producing the same private state.

Keep the scope auditable

The release note records what moved and what did not. Other authors' articles, petition records, and consent instruments were explicitly outside the withdrawal.

That boundary matters for operational safety. A vague request to remove related content can grow into an accidental purge. A slug list, route list, and named exclusions give reviewers a finite change to inspect.

A safe withdrawal therefore leaves four kinds of evidence:

Scope: the exact records and routes being withdrawn
State: unpublished records and preserved source files
Public absence: 404 responses, clean listings, and clean sitemaps
Operational follow-up: reindexing and production verification

Deletion destroys options. A reversible migration removes publication authority while keeping the source and history needed for whatever comes next.

Baamaapii

Separate AI drafting from publication authority

Russell Jones — Mon, 02 Nov 2026 14:05:30 +0000

Ahnii!

This blog used to put the whole publishing job inside one GitHub Actions workflow. The job checked capacity, called an AI CLI, wrote the article, built the site, committed the result, and handed social delivery to Buffer. That was convenient until the hosted generator became the least reliable part of the system.

The replacement did not move the entire pipeline onto my computer. It split the pipeline at a more useful boundary: judgment happens locally, while publication authority stays behind deterministic checks.

That distinction matters. An AI agent is useful for reading source changes, deciding whether a topic deserves an article, and drafting prose. It should not get to redefine the conditions under which that prose becomes public.

Make the cloud gate read-only

The old content-autopilot.yml was a 250-line publishing workflow with repository write access. The replacement is a small, manually dispatched preflight with read-only repository permissions.

Its job is to inspect current state and return evidence:

the Toronto calendar date
the exact main commit checked
whether an article was already published that day
whether the social outbox is still pending
whether Buffer has room
which mined issues are still unprocessed

The result is uploaded as a JSON artifact. It includes a caller-supplied request ID, so a local run can find the exact workflow execution after an uncertain network response instead of dispatching a duplicate.

The artifact is not merely a list of suggestions. It is a short-lived authorization tied to a date and a Git commit. The local publication tool rejects it after two hours, rejects it on the wrong Toronto day, and rejects it if the checkout no longer matches the recorded baseSha.

That turns a potentially fuzzy handoff into a concrete contract:

preflight artifact + exact checkout + selected candidate = eligible draft

If any term changes, the run goes back through preflight.

Keep judgment local

The local Codex session handles the part that benefits from context and judgment. It reads the candidate issue as a lead, opens the actual source commit, searches published work for overlap, and can decide that no candidate is worth publishing.

That final option is important. A daily schedule is permission to look, not an obligation to manufacture an article.

When a topic does merit a post, the local run creates only the article and its three social variants. A result file names the source issue, slug, expected paths, and the HTTPS sources that were actually checked. The staging script then validates the result against the preflight before it touches publication records.

The validation is intentionally boring. It checks path shapes, frontmatter, date, source links, social sections, canonical URLs, duplicate issue numbers, daily limits, and a pending outbox. It also refuses to overwrite an existing article. The prose still requires judgment, but the publication invariants do not.

Commit one bounded transaction

Staging produces five related changes:

the Hugo page bundle
the social copy
a dated publication record
the processed-issue ledger
the Buffer outbox

Those files are committed together through a pull request. This is the durable boundary of the run. If the process stops before that commit, there is no published record to reconcile. If it stops after the commit, the ledger and outbox describe exactly what remains.

The pull request receives a separate Content Validation check. That check installs dependencies from scratch, runs the Node test suite, validates every saved publication record, and builds the production Hugo site. The local agent can propose a change, but it cannot declare its own proposal deployable.

The merge is also pinned to the reviewed head commit. If the branch changes after validation, the merge command fails instead of silently accepting a different revision.

Let deployment unlock delivery

Merging the article still does not send social posts. Pages must successfully deploy the exact merge first.

Only then does Buffer Posting read the durable outbox. Before it mutates anything, it verifies that each canonical article URL is publicly reachable and that the rendered page contains canonical publication evidence. A successful Git commit is not treated as proof that readers can reach the article.

Social delivery has its own reconciliation rules. The delivery script scans scheduled, sending, sent, failed, and draft posts. It matches exact normalized copy, rejects multiple matches, and records a receipt as it works. If a create response is uncertain, the next run inspects Buffer instead of blindly creating another post.

After all three channels are verified, the workflow appends the receipt to a delivery ledger and clears the outbox. Until that happens, the next preflight refuses to authorize another article.

Authority belongs in the reproducible layer

Moving AI work out of GitHub Actions solved a billing and reliability problem, but the architectural improvement is broader.

The local agent owns interpretation: what changed, what is useful, what overlaps, and how to explain it. Versioned scripts and cloud checks own authority: whether the source state is current, whether the records are consistent, whether the site builds, whether the article is live, and whether delivery already happened.

That separation makes the pipeline easier to resume because every boundary leaves evidence. It also makes the AI replaceable. The drafting tool can change without moving the gates, ledgers, deployment checks, or delivery contracts that keep publication safe.

Baamaapii

Expose validated registries without a second authority

Russell Jones — Sun, 01 Nov 2026 14:09:42 +0000

Ahnii!

A framework can validate a registry during boot and still create a security problem if later consumers receive a different instance. Validation only protects the object that was actually validated.

This post covers a versioned Waaseyaa fix that exposed the kernel's role repository to provider factories. The pattern applies to permission catalogues, route snapshots, schema registries, and other boot-time authorities.

Keep one owner for validated state

Waaseyaa service providers contribute roles and permissions during kernel boot. The kernel collects those contributions, validates them, and retains a role repository for runtime use.

Provider factories also need to resolve that repository. The dangerous shortcuts are easy to imagine:

Build another repository from provider declarations.
Let a sibling provider register its own repository binding.
Resolve a partially composed repository during provider registration.
Call contribution methods again after validation.

Each shortcut creates a second authority or changes the inputs after they were checked.

The fix kept ownership with the kernel. The provider service bus received a lazy accessor to the kernel's repository instead of a factory that could reconstruct it.

Return nothing before composition is complete

Timing is part of the contract.

During provider registration, role contributions have not finished composing. Returning a repository at that point would expose incomplete or unvalidated state. The accessor therefore returns null before the kernel has completed catalogue composition.

After composition, provider boot hooks receive the exact repository retained by the kernel. The service bus does not synthesize a fallback.

This produces a useful lifecycle rule:

Phase	Repository result
Provider registration	Unavailable
Catalogue collection and validation	Kernel-owned work in progress
Provider boot	Validated kernel instance
Runtime factory resolution	Same kernel instance

Making the pre-composition state unavailable is better than returning an object that looks usable but has not crossed the validation gate.

Give kernel authority precedence over provider bindings

A provider may try to register a binding for the same repository type. That binding must not replace the kernel authority.

The service bus checks the role repository type before consulting sibling providers. If the kernel accessor is absent or not ready, resolution returns null. It does not fall through to a provider-owned replacement.

That precedence rule matters because dependency injection containers often treat the nearest binding as authoritative. For validated infrastructure, ownership must be encoded explicitly. Registration order should not decide which security catalogue wins.

Preserve identity, not only equivalent values

Two repositories can contain equal-looking roles and still represent different authority.

Identity proves that provider factories consume the object that passed kernel validation. Rebuilding an equivalent repository loses that proof and can hide timing bugs, stale data, or a second call to stateful contribution code.

The qualification used a provider whose roles() result changes on every call. The tests proved that:

The contribution method was consulted exactly once.
The repository was unavailable during registration.
The provider received the kernel repository during boot.
Repeated service resolution returned the same instance.
A sibling replacement binding was ignored.

The stateful fixture is deliberate. A provider that always returns the same values would not expose an accidental second collection pass.

Wire every construction path

The service bus was constructed in several kernel paths, including provider discovery, access-policy discovery, field-read installation, schedule registration, and query validation.

The fix passed the same lazy repository accessor through each path. Missing one construction site would create phase-dependent behavior where a factory resolves correctly in one subsystem and fails or falls back in another.

When you add a kernel-owned service to a shared resolver, search for every place that resolver is constructed. Test the identity and refusal rules through the public boot lifecycle, not only through a directly instantiated helper.

Test authority as a lifecycle invariant

The important assertion is not simply that dependency resolution returns a repository. Test the full boundary:

Contributions are collected once.
Invalid grants fail before provider boot.
Pre-composition resolution returns nothing.
Post-composition resolution returns the validated object.
Provider bindings cannot replace it.
Every consumer receives the same identity.

Validated registries need both content checks and custody checks. Validate the catalogue, keep one owner, expose it only after composition, and preserve its identity everywhere it is consumed.

Baamaapii

Delegate account management without granting admin

Russell Jones — Sat, 31 Oct 2026 13:01:53 +0000

Ahnii!

A staff member may need to update accounts in one approved roster without gaining every power carried by an administrator role. That is a delegation problem, not a reason to widen the administrator boundary.

This post covers a versioned Waaseyaa authorization change that added consumer-scoped account management, then narrowed it through review. The useful pattern is to delegate exact decisions while keeping privileged fields, account creation, deletion, and credentials behind their existing boundaries.

Start with the authority you actually need

A broad permission such as administer users can authorize much more than the workflow requires. It may cover role changes, account deletion, and targets outside the consumer's roster.

Write down the smaller decision instead:

Which authenticated actor may act?
Which exact account may they update?
Which operation may they perform?
Which fields must remain unavailable?
What evidence binds the target to the consumer's scope?

The framework extension introduced an optional delegate inside the canonical user access policy. The consumer supplies the roster and consent decision. The framework continues to compose the final authorization result.

Without a delegate binding, the old refusal remains. This makes delegation an explicit application choice instead of a new default permission.

Pass immutable authorization input

The delegate receives an authenticated authorization principal and the exact target account. It does not receive a mutable account object that application code can alter before asking for a decision.

That distinction matters in retained workers and long-running processes. Authorization should depend on a snapshot of identity, roles, and permissions for the current request. It should not retain an actor from an earlier request.

The provider-discovery tests exercised both bound and unbound policies. They also sent different actors through the same retained handler and then returned to the first actor. That proves the delegate binding survives discovery without turning request identity into service state.

Direct legacy callers still pass through a runtime type guard. An authenticated object is not enough. Delegated decisions require the immutable principal contract.

Keep creation behind a separate intake boundary

The first version of the delegate included an actor-only account creation decision. Review removed it.

An actor-only predicate can prove that a clerk is generally trusted, but it cannot prove that this new account belongs to an approved roster entry or verified consent record. There is no target yet, so the most important subject of the decision is missing.

The hardened design keeps generic account creation administrator-only. Consumer creation needs a separate provisioning boundary with an explicit approved-intake reference.

This is a useful review question for any delegated API: does the method receive enough evidence to authorize the thing it creates? If it receives only the actor, it may be too broad for the workflow it claims to protect.

Do not release privileged fields

Permission to update an account does not imply permission to edit every account field.

The delegate cannot authorize edits to:

Roles or permissions
Email verification state
Password or legacy password material
Two-factor secrets and recovery data
Session-generation data
Generic active-status fields
Account deletion

Those restrictions stay in the canonical field and entity policies. A consumer cannot bypass them by returning true from its delegate.

The initial candidate allowed delegated active-status edits through the generic field surface. The integrated behavior moved that change to a dedicated lifecycle operation. This is the safer boundary because disabling an account has a required side effect: existing sessions must be revoked.

Couple status changes to session revocation

The account lifecycle service checks two independent decisions before changing status:

The actor may update this exact target.
The actor may perform the dedicated active-status operation.

It also refuses self-administration through this path.

When disabling an account, the service increments the session generation and changes the active flag before one repository save. Existing sessions bound to the previous generation become invalid with the same durable write that disables the account.

Re-enabling the account does not restore the old generation. An unchanged status produces no write, and an exhausted generation counter fails instead of wrapping.

That is why the generic field write was not enough. A security-sensitive state change belongs behind the operation that can enforce all of its invariants.

Test the refusals as part of the contract

The useful tests are not limited to the admitted clerk and target. They also prove that the boundary refuses:

Another actor
Another target
Anonymous input
A mutable legacy account object
Account creation without approved intake
Privileged and credential fields
Deletion
Status changes without both delegate decisions
Self-disable through the lifecycle service

Keep those negative cases beside the success path. They describe the authority the delegate does not have, which is the most important part of a narrow delegation contract.

Delegation works when it adds one bounded capability without creating a second administrator role. Pass immutable request identity, bind decisions to exact targets, keep creation tied to verified intake, and route security-sensitive mutations through services that enforce their required side effects.

Baamaapii

Prove SMTP authentication on every connection

Russell Jones — Fri, 30 Oct 2026 13:06:21 +0000

Ahnii!

An SMTP server advertising authentication is not the same as the client successfully authenticating. The first fact describes a capability. The second is security state that belongs to one connection.

This post follows a versioned Waaseyaa mail transport from its initial authenticated SMTP implementation through review-driven hardening. The useful lesson is broader than one library: require fresh authentication evidence after every handshake, including reconnects.

Make transport selection explicit

Email configuration should name the transport it intends to use. Do not infer production delivery from a loose collection of environment variables.

The implementation accepted a bounded set of transports, including local capture, an in-memory test transport, a provider transport, and authenticated SMTP. SMTP configuration was validated before a connection could be attempted. It required a valid host, port, username, secret source, and supported authentication method.

Fail early on incomplete or ambiguous configuration. A value that looks unusual, such as the username 0, must not disappear because a truthiness check mistakes it for an absent value.

Establish a verified encrypted channel

Authentication credentials should only cross a channel whose peer has been verified.

The transport required STARTTLS and configured the socket to:

Verify the peer certificate
Verify the peer name
Reject self-signed certificates
Limit TLS negotiation to supported modern protocol versions

The socket itself also had to be a valid stream before TLS options were applied. That check turns an unexpected runtime value into a controlled failure instead of letting it reach lower-level networking calls.

Encryption is a prerequisite here, not proof of authentication. Keep those states separate.

Track completed authentication, not advertised capability

The first implementation checked that the server advertised the requested AUTH mechanism before sending mail. That is a useful capability check, but review exposed a missing boundary: a reconnect creates a new protocol session.

A server can advertise AUTH on one connection, accept authentication, and then behave differently on the next connection. It can omit AUTH or attempt an EHLO-to-HELO downgrade. If the client remembers only what a previous server greeting advertised, it may confuse old connection state with current authorization.

The hardened transport instead records successful authentication only after the server returns the expected success response. It clears that state whenever a fresh greeting begins. Before a message is sent, the current connection must have completed its own authentication exchange.

That produces a simple invariant:

Every connection that sends a message must independently prove successful authentication.

If a reconnect cannot satisfy that invariant, delivery stops. The client does not continue through a weaker HELO path.

Protect both the envelope and the failure path

Mail safety extends beyond the connection handshake.

The transport rejected reserved routing headers supplied through message metadata so application input could not quietly replace envelope decisions. It also translated provider and SMTP exceptions into a stable delivery failure without attaching the original exception. That prevents credentials, server transcripts, and provider details from leaking through an exception chain.

Keep detailed diagnostics in an appropriately protected operational channel. Public application errors should describe the failed operation without replaying secrets or protocol conversations.

Test protocol transitions, not only successful delivery

A happy-path SMTP test proves very little about reconnect behavior. Use a disposable test server that can control each protocol exchange and record what the client sent.

The qualification covered:

LOGIN and XOAUTH2 success
Missing or mismatched AUTH capabilities
Invalid and falsey configuration values
TLS verification failures
A second connection that omits AUTH
A second connection that tries to fall back from EHLO to HELO
Redaction of the public failure surface

TLS tests ran the mail client in a separate PHP process so certificate authority configuration was present when the runtime initialized. That is a good general rule for tests involving process-start configuration: exercise the real boundary instead of mutating global state after initialization and assuming the result is equivalent.

The important outcome was not merely that authenticated SMTP worked. It was that authentication could not be inherited across connections, inferred from an advertisement, or bypassed through downgrade behavior.

Baamaapii

Separate installation from production activation

Russell Jones — Thu, 29 Oct 2026 13:05:46 +0000

Ahnii!

A successful installer does not prove that an application is ready to serve production traffic. It proves that the installer completed its own bounded job.

This post covers a production qualification pattern from a versioned Waaseyaa candidate: test installation, activation evidence, and HTTP runtime as separate gates, then stop at the first failing boundary.

Give the installer narrow authority

An installer may need powers that ordinary application boot must not have. It can create the configured database, apply migrations, synchronize entity schemas, and initialize configuration.

Keep that authority attached to the installation command. Help output, invalid options, unexpected arguments, and unrelated commands should not create storage as a side effect.

The qualified candidate tested these boundaries directly:

A valid production install created the selected SQLite database.
Repeating installation preserved an existing content witness and configuration activation rows.
An invalid production secret failed before creating storage.
Existing foreign schema drift caused a refusal without deleting the foreign row.
Ordinary commands still refused an absent database instead of creating it.

This is more useful than one broad end-to-end success assertion. Each check tells you which command owns a mutation and which commands must remain read-only.

Do not manufacture activation evidence during setup

Installation and activation answer different questions.

Installation asks whether the application can create and initialize its operational state. Field-access activation asks whether the exact installed framework, schema, scanner generation, and field classifications have been reviewed and are ready for production reads.

The installer intentionally did not create the field-access activation artifact. A separate preflight command inspected the live installation. Read-only execution reported its result without writing the artifact. Only an explicit artifact-writing option published the evidence later consumed by normal boot.

That separation prevents setup from approving itself. It also lets you prove several refusal cases:

Missing evidence blocks activation.
A malformed artifact is rejected.
A different scanner generation is rejected.
A framework or schema identity mismatch is stale.
A changed checksum or readiness flag is invalid.
Any unresolved blocker keeps the result not ready.

The important part is not the filename or command name. The important part is that reviewed evidence is produced explicitly and bound to the inputs it actually describes.

Qualify each installation independently

Two installations can produce similar results without sharing the same identity.

In the recorded qualification, development and no-dev installations had different discovered fields, schema fingerprints, and preflight checksums. Each installation used its own vendor tree, database, schema, scan, and artifact. No artifact was copied from one environment to the other.

That matters because a passing result is not portable merely because the output looks familiar. Reuse requires source, dependency, schema, scanner, and execution equivalence. When those inputs differ, generate and review evidence again.

Test the actual runtime after the CLI gates

Once installation and activation pass, exercise the same server path production will use.

The candidate qualification checked cold, warm, and restarted Apache with PHP-FPM. It confirmed production mode, disabled debugging, disabled development fallback, and a real application-owned response marker. A separate no-dev installation also proved that the runtime did not depend on PHPUnit.

The sequence was deliberate:

Install the application.
Run the read-only activation preflight.
Explicitly write the reviewed activation artifact.
Confirm ordinary CLI boot consumes it.
Start the production web stack.
Test cold, warm, and restarted requests.
Run negative controls and restore the exact environment.

Do not collapse those checks into one green label. A prerequisite, a generated artifact, and a runtime response are separate pieces of evidence.

Preserve the first failing boundary

The versioned qualification first reached a homepage only after the activation artifact existed. Its next unknown-route request returned a generic 500 instead of the required 404. The record preserved that result and handed the failure to the issue that owned error handling and diagnostics.

That is the right stopping rule. Do not patch an unrelated subsystem inside a qualification run just to make the journey green. Record:

The exact source and dependency identity
The environment and server mode
The command or request that failed
The public response
The private diagnostic evidence that is safe to retain
The limits of what the evidence proves

A clean production qualification is not a story about everything working. It is a chain of bounded claims that stops honestly when the next claim cannot be made.

Baamaapii

Track campaign conversions without storing contact details

Russell Jones — Wed, 28 Oct 2026 13:10:26 +0000

Ahnii!

Campaign attribution usually starts with a simple question: which shared link led to a useful action? The implementation gets risky when analytics and contact data start bleeding into each other.

This post covers a narrower design: count landings and saved contact messages for registered campaigns while keeping names, email addresses, messages, raw query strings, and visitor identifiers out of the conversion table.

Register campaigns instead of accepting arbitrary tags

Do not treat every UTM value as trusted analytics data. Use a finite registry that binds one internal campaign key to the exact public route and exact tag set you expect.

That boundary gives you several useful properties:

Unknown tags never become campaign labels.
Duplicate or partial parameters do not create attribution.
A valid tag set on the wrong route is rejected.
Test campaigns can be marked and excluded from production totals.
Click IDs and unrelated query parameters never enter storage.

The browser only carries the internal key after the complete registered link matches. This keeps reporting labels under editorial control instead of letting arbitrary request data shape your analytics.

Keep attribution short-lived and same-tab

For a contact form reached after a landing page, you need a small amount of continuity. You do not need a durable visitor profile.

The implementation stores a registered campaign key and a 30-minute expiry in same-tab session storage. A second valid campaign replaces the first. Invalid explicit campaign tags clear the old value. When session storage is unavailable, attribution can remain in memory for the current page and then disappear.

This is deliberately limited:

There is no analytics cookie.
There is no cross-tab identity.
There is no name, email, message, or raw URL in the attribution state.
Do Not Track or Global Privacy Control clears the state and disables collection.

Those limits mean the report is not a complete readership count. That is acceptable when the goal is directional campaign measurement, not surveillance.

Count conversions only after the contact is saved

A public analytics collector should never be allowed to claim that a conversion happened. The server already knows when the contact form passes validation, rate limiting, bot checks, and persistence.

Record the conversion at that trusted boundary. In this implementation, the contact row and conversion event are written inside the same database transaction. If the conversion write fails, the tracked contact save rolls back too. The response cannot report success for a message while silently losing its associated measurement.

The conversion event contains only:

The event type
A known campaign key or null
A random event key
A timestamp

The contact record keeps the personal information needed for a reply. The analytics table does not receive the contact row ID or any contact content.

Deduplicate landings without creating a visitor profile

Repeated delivery of the same pageview can happen through retries or browser behaviour. A random pageview ID can be hashed into an event key so the same landing is counted once.

That key is scoped to deduplication. It is not reused to join the landing to a person, a contact record, or activity on another day. The report aggregates campaign landings and saved messages without exposing an individual journey.

Test the refusal paths

The useful tests are not only the happy path. Prove that the boundaries hold when inputs are incomplete or hostile.

Cover at least these cases:

Unknown, duplicate, partial, expired, and wrong-route campaign tags are rejected.
Do Not Track and Global Privacy Control prevent analytics while the contact form still works.
Bots, invalid forms, honeypots, and rate-limited requests do not count as conversions.
The public collector cannot submit a conversion event.
Repeated delivery of one pageview counts one landing.
Analytics failure rolls back a tracked contact save.
Stored analytics rows contain no email address or message text.
Test campaigns stay out of production totals.

This design does not prove that someone saw the original social post. Reshares keep the same registered tag, scripts can be blocked, and privacy choices reduce the count. Report visits and saved messages for a link, not unique people or causal certainty.

Baamaapii

Repair stale digest pins without weakening verification

Russell Jones — Tue, 27 Oct 2026 13:05:53 +0000

Ahnii!

A strict digest check is supposed to stop old configuration from silently selecting changed generated output. When a reviewed generator changes, that protection can also make a reference fixture fail until its pinned identity is migrated.

This post shows how to repair that failure without weakening the integrity check, using a Waaseyaa reference consumer as the example.

Understand what the digest protects

The reference application selects a generated recipe in YAML:

recipes:
  - id: published_content
    version: 1
    capability: published_content
    artifact_digest: cf8f1932dea7f7dc08ccf2cefbf42465d5c2838b1d0e1fbd3cf62a63da580f11

The digest identifies the reviewed recipe artifact, not just the recipe name and version. If the recipe's generated files or contract change, an older selection should not claim that it still describes the installed output.

That refusal is useful. It turns a silent compatibility mismatch into an explicit migration decision.

Classify the failure before changing code

The hosted reference consumer failed because its checked-in answers still pinned the previous recipe digest. A fresh installed consumer reproduced the same mismatch through project:init --dry-run.

There are two very different possible causes:

Cause	Correct response
Installed recipe changed without an approved contract update	Stop and repair the producer or release process
Reviewed recipe changed but its reference fixture kept the old digest	Migrate the fixture and prove it against the installed recipe

Do not make digest comparison optional just because the failure appeared in a test fixture. That would also allow genuinely stale applications to accept changed generated output.

In this case, the reviewed recipe already owned the new digest. The missing change was in the reference consumer's selection.

Update the selection, not the verifier

The repair changed one value in the reference answers file: the previous digest was replaced with the digest of the reviewed installed recipe.

The validation rules stayed strict. Runtime boot, installation authority, persistence behavior, and normal refusal controls did not need to change.

This is an important boundary for code generation:

the producer defines the artifact identity;
the consumer pins the identity it reviewed;
a changed identity requires an explicit consumer migration;
the verifier continues refusing mismatches.

If you instead loosen the verifier, you erase the evidence that the consumer has reviewed the new generated contract.

Test the real reference fixture

Updating a hash by hand can make the immediate error disappear without proving that the complete reference configuration works. Add a contract test that loads the actual fixture and sends it through the installed recipe:

#[Test]
public function theReferenceSelectionRendersWithTheInstalledPublishedContentRecipe(): void
{
    $path = dirname(__DIR__) . '/ReferenceConsumer/site.answers.yaml';
    $manifest = new SiteManifestParser()
        ->parse((string) file_get_contents($path), $path);

    self::assertNotEmpty(
        new PublishedContentRecipe()->render($manifest),
    );
}

This test checks the real answers file rather than a smaller duplicate fixture. It exercises three things together:

the reference YAML parses as a site manifest;
its pinned recipe identity matches the installed recipe;
the recipe can render output for that manifest.

The test was captured failing with the stale digest before the fixture was updated. That proves the regression test detects the original mismatch.

Keep the negative test

A successful real-fixture test is only half of the contract. Keep a separate test that substitutes the wrong digest and expects refusal.

The two tests answer different questions:

Test	Evidence
Actual reference selection renders	The maintained fixture matches the installed reviewed recipe
Substituted digest is refused	Integrity checking still rejects an unreviewed identity

Without the first test, fixture drift can reach hosted qualification. Without the second, a permissive implementation could make every fixture pass.

Requalify the new identity

Once the fixture and regression test change, you have a new candidate. Run the focused contract tests, the broader governed preflight, and the hosted consumers again against the exact new commit.

Do not reuse the old green results. They describe the old candidate. Do not repair a failed installed consumer in place either. A fresh consumer gives you evidence about the new fixture without mixing it with state from the failed attempt.

The final checklist is short:

Reproduce the digest mismatch from a clean consumer.
Confirm whether the producer or the pinned fixture is stale.
Update only the reviewed consumer selection when it is a fixture migration.
Add a test that renders the actual reference manifest.
Retain a negative test for a substituted digest.
Requalify the new commit through fresh consumers.

Strict digest checks create migration work on purpose. Preserve that boundary, migrate the fixture explicitly, and test both acceptance and refusal.

Baamaapii

Make integration tests independent of your local .env

Russell Jones — Mon, 26 Oct 2026 13:07:02 +0000

Ahnii!

An integration test can pass on your computer because your local .env quietly supplies a database path, application secret, or storage directory. The same test then fails in CI, or worse, touches a real local resource that was never meant to be part of the test.

This post shows how to make a PHP integration test own its complete environment, using a Waaseyaa media publishing test as the concrete example.

Hidden configuration is a test dependency

The test boots the real CLI, initializes a database, writes media files, and exercises the HTTP publishing path. That means it depends on more than the values named in the test method.

Its runtime needs:

an explicit application environment;
debug mode disabled;
a database path;
valid application and JWT secrets;
isolated upload and file-storage roots.

If even one value falls through to your shell or .env, the test is not self-contained. A developer with a configured application may get a pass while a clean runner gets a boot error.

Save every variable the test owns

Before changing the process environment, save the original value of every variable the test will replace:

/** @var array<string, string|false> */
private array $originalEnvironment = [];

foreach ([
    'APP_ENV',
    'APP_DEBUG',
    'WAASEYAA_DB',
    'WAASEYAA_APP_SECRET',
    'WAASEYAA_JWT_SECRET',
    'WAASEYAA_MEDIA_UPLOADS_DIR',
    'WAASEYAA_FILES_ROOT',
] as $name) {
    $this->originalEnvironment[$name] = getenv($name);
}

getenv() returns false when a variable was absent. Keep that distinction. An absent variable and a variable set to an empty string can take different configuration paths.

The list should be explicit. It documents the environment boundary of the test and makes new dependencies visible in review.

Create unique temporary resources

A fixed test database or upload directory creates collisions between runs and leaves stale state available to the next test. Generate one suffix, then use it for every related temporary path:

$suffix = bin2hex(random_bytes(8));

$this->databasePath = sys_get_temp_dir()
    . '/rhtcircle-media-' . $suffix . '.sqlite';

$this->uploadsDir = sys_get_temp_dir()
    . '/rhtcircle-media-' . $suffix;

mkdir($this->uploadsDir, 0700, true);

This gives the database and file storage a shared run identity without letting one run reuse another run's files. The restrictive directory mode also matches the fact that these are private test artifacts, not public fixtures.

Supply valid test-only secrets

Do not make the test depend on development credentials. Generate values that satisfy the application's real configuration rules:

putenv('APP_ENV=testing');
putenv('APP_DEBUG=false');
putenv('WAASEYAA_DB=' . $this->databasePath);
putenv('WAASEYAA_APP_SECRET=base64:' . base64_encode(random_bytes(32)));
putenv('WAASEYAA_JWT_SECRET=' . bin2hex(random_bytes(32)));
putenv('WAASEYAA_MEDIA_UPLOADS_DIR=' . $this->uploadsDir);
putenv('WAASEYAA_FILES_ROOT=' . $this->uploadsDir);

These secrets exist only for the test process. They are random, valid for the boot path being exercised, and unrelated to local or production values.

Avoid a short placeholder such as test-secret when the application expects a specific strength or format. A weak fixture can bypass the same validation that protects the real system, which means your integration test no longer represents a valid installation.

Restore absence as absence

Teardown must restore both kinds of original state:

foreach ($this->originalEnvironment as $name => $value) {
    putenv($value === false ? $name : $name . '=' . $value);
}

Calling putenv($name) removes a variable. Calling putenv($name . '=') leaves it present with an empty value. That difference is easy to miss and can leak configuration into later tests.

The test also removes its database and upload files. Environment restoration and filesystem cleanup belong in the same lifecycle because both are part of the temporary application state.

Watch for process-global state

putenv() changes the environment for the current PHP process. This is practical for a test that launches application entrypoints, but it is still global mutable state.

Use these controls when your suite grows:

run environment-mutating tests in separate processes or a serialized group;
give every run unique database and storage paths;
restore variables in teardown even after an assertion fails;
keep the owned-variable list next to setup and teardown;
never read secrets from the developer's real .env as test fixtures.

PHPUnit calls tearDown() after each completed test lifecycle, but setup code can fail too. If resource creation becomes more complex, wrap partial setup in guarded cleanup or move it into helpers that can undo their own work.

Verify the boundary

A clean test should answer these questions:

Check	Expected result
Local `.env` is missing	Test still boots
Developer secrets are different	Test behavior is unchanged
Two runs use temporary storage	Paths do not collide
A later test reads the environment	It sees the original values
The test fails halfway through	Temporary state is still cleaned up

The point is not simply to make CI green. It is to make the test prove the same thing everywhere. Once the test owns its full configuration, a pass describes application behavior instead of the accidental state of one developer machine.

Baamaapii

Preserve failed test evidence before you retry

Russell Jones — Sun, 25 Oct 2026 13:09:26 +0000

Ahnii!

A qualification harness has a harder job than an ordinary test suite. It must tell you whether a real installation worked, but it also has to preserve enough evidence to explain a failure without leaking private inputs.

This post covers five controls I used while building a published-consumer qualification lane for the Waaseyaa framework. The examples come from a specific PHP and Docker harness, but the design applies to any CI job that launches real services and produces evidence for later review.

Start the clock before setup

If a harness starts its timeout after checkout and dependency installation, those steps are outside its claimed execution budget. A slow setup can leave too little time to stop services, export state, encrypt it, and upload the result.

The workflow records its start time in the first executable step:

- name: Start the absolute qualification and custody clock
  run: echo "J1_JOB_STARTED_AT=$(date +%s)" >> "$GITHUB_ENV"

The PHP harness then derives one deadline from that timestamp:

$started = (string) getenv('J1_JOB_STARTED_AT');
$this->need(ctype_digit($started) && (int) $started <= time(), 'Workflow start identity required');
$this->deadline = (int) $started + 30 * 60;

Every subprocess receives only the time remaining. Finalization gets a separate reserved window for stopping and exporting containers, sealing files, and writing the result. The workflow still has a larger outer timeout, so runner cleanup and artifact upload have room to finish.

The useful rule is simple: the budget begins when work begins, not when the interesting test begins.

Record resource ownership before launch

Container startup can return an uncertain result. The client may time out even though the daemon created the container. If your cleanup list is updated only after a successful launch, that container disappears from your accounting.

The harness first proves that each run-owned container name is absent. It then records the name before calling docker run:

$this->containers[] = $name;
$this->run('container-start', [
    'docker', 'run', '-d', '--name', $name,
    '--memory', '2g', '--cpus', '2',
    'j1-s1:' . getenv('GITHUB_RUN_ID'),
]);

Finalization inspects every possibly created name. An absent name becomes an explicit custody record. A present container is stopped, inspected, and exported. If inspection itself fails, custody remains incomplete.

This avoids a dangerous assumption: a failed launch command does not prove that no resource exists.

Separate public evidence from private recovery state

A useful failure report and a restorable snapshot have different audiences.

The public evidence stream contains sanitized JSON records, step timings, hashes, and failure classifications. The private snapshot contains the full application bind, environment files, database side files, raw process streams, and exported container filesystems. That snapshot is encrypted before upload.

Redaction also has to match the encoding used by the output format. Replacing only the literal secret is not enough when JSON can escape characters such as /. The harness replaces both forms:

foreach ($this->secrets as $secret) {
    $escaped = substr(json_encode($secret, JSON_THROW_ON_ERROR), 1, -1);
    $data = str_replace([$secret, $escaped], '[REDACTED]', $data);
}

A regression test uses a synthetic secret containing / and + to prove that the JSON representation is redacted. The private source remains inside the encrypted snapshot rather than being copied into the public report.

Preserve the first failure

An automatic retry can turn a useful failure into a misleading pass. It can also mutate the application you need to inspect.

The qualification lane records the first failure, freezes any possibly created resources, and seals the original state. A new attempt needs a fresh application and a new snapshot identity. The failed instance is not repaired into success.

That distinction matters when a test harness is qualifying a release rather than merely checking a code path. You need to know what the first published installation did, not what it did after an unrecorded recovery sequence.

Test the observer against reality

Two early failures were caused by the harness, not the framework.

The first expected SQLite's database_list pragma to return exactly one row. A real connection can contain one file-backed main database and an unbacked temp schema. The corrected predicate allows that normal temp row while still refusing additional attached databases, path escapes, symlinks, incorrect pragmas, and duplicate rows.

The second expected an entire log event to be JSON. The actual formatter writes the message as a text prefix and only the context as JSON. The corrected parser anchors extraction to the exact critical channel and message, then decodes the following context. Tests feed it real formatter output and prove that warnings, truncated data, and unrelated JSON are ignored.

In both cases, the right repair was to correct the observer and preserve the failed run. Changing runtime behavior to satisfy a mistaken harness would have hidden the real contract.

A practical checklist

Before trusting a qualification lane, check that it can answer these questions:

When did the total budget begin?
Which resources might have been created, even after an uncertain command result?
Can every resource be stopped, inspected, and exported?
Which evidence is safe to publish?
Is private recovery state encrypted and integrity-checked?
Does a retry create a fresh identity instead of modifying the failed instance?
Are parsers and topology checks tested against output from the real tools?
Can the final result say that custody is incomplete instead of claiming a clean failure?

The goal is not to collect as many logs as possible. It is to make each result explainable. A pass should identify exactly what was tested. A failure should preserve the first state that failed. An uncertain cleanup should remain uncertain.

That is what turns a CI job into qualification evidence.

Baamaapii

CLI help must not mutate your filesystem

Russell Jones — Sat, 24 Oct 2026 13:06:40 +0000

Ahnii!

Running install:init --help should print help. It should not create a database.

That sounds obvious, but command selection often happens before input validation. If your console kernel sees a mutating command name and boots the application immediately, help and invalid options can trigger storage setup before the CLI framework decides not to execute the command.

A recent Waaseyaa installer repair separates command selection from validated execution. This post covers the boundary and the real-entrypoint tests that prove it.

Selection is not execution

Console kernels often inspect the first argument to choose a boot mode:

if ($input->getFirstArgument() === 'install:init') {
    // Boot with installation authority.
}

The token identifies the requested command, but it does not prove the command will run.

Symfony Console still needs to handle cases such as:

install:init --help;
install:init -h;
an unknown option;
an unexpected argument;
missing required input.

Help exits successfully without executing the handler. Invalid input exits with a usage error. Neither case should boot a mode that can create storage.

The original Waaseyaa path selected installation boot from the raw command token. That boot could prepare the configured database directory before Symfony processed help or rejected the input.

The visible command never ran, but its boot path had already mutated the filesystem.

Put authority inside the execution callback

The repaired kernel builds a small console application containing the canonical install:init command, then replaces its execution callback:

$application = new WaaseyaaConsoleApplication(
    version: new VersionResolver($this->projectRoot)->resolve(),
    logger: $this->logger,
);

$command = MigrateServiceProvider::installInitCommand();
$command->setCode(function () use ($input, $output): int {
    $this->initializingDatabase = true;
    try {
        $this->bootForSchemaSync();
    } finally {
        $this->initializingDatabase = false;
    }

    return new ConsoleApplicationFactory(
        kernel: $this,
        container: $this->buildHandlerContainer(),
        providers: $this->getProviders(),
        logger: $this->logger,
    )->create()->run($input, $output);
});

$application->addCommand($command);

return $application->run($input, $output);

Symfony parses the input, renders help, and validates arguments and options before entering the callback. Installation boot now happens only on the execution path.

The important part is not setCode() itself. The important part is where the authority begins.

Phase	May create storage?
Read command name	No
Render help	No
Validate arguments and options	No
Enter the validated execution callback	Yes
Complete or fail execution	Authority restored in `finally`

This makes the mutation boundary match the command framework's lifecycle.

Share the command definition

Moving validation before boot can tempt you to build a second parser in the kernel. That creates drift between pre-boot validation and the command registered after boot.

Waaseyaa avoids that by exposing one command factory:

public static function installInitCommand(): HandlerCommand
{
    return new HandlerCommand(
        name: 'install:init',
        description: 'Initialize a fresh installation: apply migrations, synchronize schema, and activate the initial configuration generation',
        handler: [InstallInitHandler::class, 'execute'],
    );
}

Both provider discovery and the pre-boot dispatch path use this definition. Arguments, options, description, and handler ownership stay in one place.

If the command changes later, help and validation change with it. The kernel does not need a parallel list of accepted input.

Keep elevated boot authority scoped

Fresh installation is unusual because it may be the only allowed path that creates a missing production database. Ordinary production boot should still refuse that state.

The kernel represents this exception with a private installation mode. The callback enables it only around schema boot and restores it in finally.

That gives you two protections:

help and invalid input never receive creation authority;
a boot exception cannot leave the kernel in installation mode.

Temporary authority should always have an obvious start, an obvious end, and failure-safe cleanup.

Test the real entrypoint and negative space

A unit test of the callback is not enough. The defect lived in the ordering between the executable, the kernel, Symfony Console, and application boot.

The integration test invokes the real CLI entrypoint with a database path under a directory that does not exist. It checks four non-executing inputs:

Input	Expected exit
`--help`	0
`-h`	0
unknown option	2
unexpected argument	2

After every invocation, the test proves the absence of:

the configured SQLite file;
its -wal sidecar;
its -shm sidecar;
the selected parent directory;
the ordinary storage directory.

Those absence checks matter. An exit code can be correct even after the application created an empty directory or touched a database file.

Test both the response and the negative space left behind.

Review pre-boot dispatch carefully

Any CLI with multiple boot modes can have this problem. Look for code that grants authority from raw argument tokens before the command framework validates input.

Pay extra attention to commands that can:

create databases or directories;
acquire migration locks;
open network connections;
load production secrets;
modify caches or generated files.

For each one, prove that help, malformed options, unexpected arguments, and missing input perform no mutation.

The command name tells you what the user selected. Only the validated execution callback tells you what the program is allowed to do.

Baamaapii

Do not let generated content replace your homepage

Russell Jones — Fri, 23 Oct 2026 13:05:35 +0000

Ahnii!

A content generator can produce valid routes and still erase the application you started with.

The failure appears when a content type uses a root-level detail route such as /{slug}. If the generator derives the collection route by removing the slug segment, it gets /. Registering that collection at the root can replace the homepage provided by your starter application.

A recent Waaseyaa route-generation repair makes the ownership rule explicit. This post covers the route policy and the tests that keep a generated content index from taking over /.

The detail route is not the collection route

Consider three content types:

Content type	Detail route	Expected collection
Page	`/{slug}`	`/page`
News	`/news/{slug}`	`/news`
Archive	`/news/archive/{slug}`	`/news/archive`

Removing the terminal slug works for the two prefixed routes. It does not work for the root-level route because the empty parent becomes /.

The original derivation followed that logic:

$route = preg_replace('#/\{[^/]+\}$#', '', $detailRoute) ?? '';

return $route === '' ? '/' : $route;

Both the homepage and the generated page collection then claimed the same literal URL. The router could serve a valid response while still serving the wrong owner.

That distinction matters. An HTTP 200 does not prove your homepage survived generation.

Give the root collection a stable name

The repaired recipe passes the bundle identifier into its collection-route function:

private function indexRoute(string $detailRoute, string $bundle): string
{
    $route = preg_replace('#/\{[^/]+\}$#', '', $detailRoute) ?? '';

    return $route === '' ? '/' . $bundle : $route;
}

The policy is small:

a root-level detail route keeps its authored /{slug} pattern;
its collection moves to /<bundle-id>;
a prefixed detail route keeps its parent as the collection;
the application homepage remains at /.

For the default page bundle, individual pages still resolve from paths such as /about, while the collection lives at /page.

This is better than inventing a global /content prefix. The bundle already provides a stable, declared name, and prefixed routes do not change unnecessarily.

Reserve literal collection paths first

Moving the collection exposes another possible collision. A root-level page bundle now owns /page, so another content type cannot also declare /page/{slug} and derive the same collection.

The recipe records each collection route while rendering definitions:

if (isset($indexRoutes[$indexRoute])) {
    throw new InvalidArgumentException(
        "Published content index route collision: {$indexRoute}"
    );
}

$indexRoutes[$indexRoute] = true;

This refuses the ambiguous site before publishing generated files. It also reserves the literal collection path ahead of the broad /{slug} detail matcher.

Route ordering can hide a collision during one request. Generation-time refusal makes the contract independent of registration order.

Test ownership, not only response codes

The focused recipe tests cover the route table directly:

/{slug} produces /page;
/news/{slug} produces /news;
/news/archive/{slug} produces /news/archive;
no generated collection may equal /;
a second collection at /page is refused.

The stronger integration check verifies the composed application:

Generate and install the minimal published-content recipe.
Request / from the real HTTP runtime.
Assert the response contains a marker owned by the application's homepage template.
Request /page.
Assert the response contains the generated page_index listing.
Repeat the homepage request cold, warm, and after restarting the server process.

The marker is important. Checking only for status 200 would accept the original bug because the generated listing also returned 200 at /.

You need evidence about which component answered, not just whether something answered.

Version the generated contract

Changing generated URLs is observable application behavior. Waaseyaa includes the collection policy in the recipe digest:

'index_routes' => [
    'root_detail' => 'bundle_path',
    'prefixed_detail' => 'parent_path',
],

That prevents an older generated selection from silently claiming the new output. Existing applications retain their routes until a reviewed regeneration adopts the changed recipe.

This is the right upgrade boundary for code generation:

fix future output at the producer;
record the new generation contract;
refuse conflicting routes before writing;
require existing applications to regenerate deliberately.

Do not patch generated metadata by hand to make verification pass. The generator, its digest, and the application output should move together.

A route-generation checklist

Before you trust a generated route set, prove these boundaries:

Boundary	Minimum proof
Homepage ownership	`/` renders an application-owned marker after generation
Root detail routes	`/{slug}` keeps details at the root without creating a root collection
Prefixed routes	Parent collection paths remain unchanged
Literal collisions	Duplicate collection URLs fail before publication
Matcher precedence	Collection literals are reserved ahead of broad slug routes
Upgrade behavior	A changed route policy changes the generation contract

Generated code is part of your application's public interface. Treat route ownership as a contract, and test the composed application that users will actually reach.

Baamaapii