DEV Community: XNeuronal

The briefing said nothing today, the reminder said today: an all-day event is a date, not an instant

XNeuronal — Thu, 10 Sep 2026 15:02:19 +0000

A tester reported that an all-day event had rung at midnight, announcing itself for today, and that the morning briefing a few hours later said nothing was planned today. Same server, same row, a few hours apart.

To keep a private report private, take an invented example with the same shape: say, a day trip on Friday 11 September, no hour given. Replaying a row like that through the code of the time was worse than the report. Thursday's briefing listed the trip as today. Friday's briefing did not list it at all. And the same date imported from the phone's calendar showed up on Friday AND on Saturday.

XNeuronal is an Android app with a Node backend in TypeScript and a Postgres database. The fix landed on 08/09/2026, in two backend commits and one app commit. Every block below is copied from the repository and lightly trimmed.

Two columns for one appointment

A dated row carries its time twice. due_local is a timestamp without time zone: the hour as the owner said it, "2026-09-11T14:00", no zone attached. due_at is a timestamptz: the instant that hour maps to in the owner's timezone, computed at the target date so that a meeting booked in August for November survives the switch to winter time.

For a timed event, that is right. For an all-day event, it hides a question. There is no hour, only a date, and the moment you store a date in a column that holds instants, somebody has to pick the instant. Every piece of code that writes the column picks it on its own.

Three writers, three instants

The first writer is the server's derivation, used when the assistant creates an event from what the owner dictated. Before the fix, deriveInstants did not know what an all-day event was:

export function deriveInstants(input, timezone) {
  const dueLocal = input.due_local ?? null;
  const endLocal = input.end_local ?? null;
  return {
    due_local: dueLocal,
    end_local: endLocal,
    due_at: dueLocal ? wallToInstant(dueLocal, timezone).toISOString() : (input.due_at ?? null),
    end_at: endLocal ? wallToInstant(endLocal, timezone).toISOString() : (input.end_at ?? null)
  };
}

An all-day Friday arrives as due_local: '2026-09-11T00:00'. Midnight on Friday, two hours ahead of UTC, is 2026-09-10T22:00:00Z: Thursday evening. A single day usually comes without an end, so end_at stays null.

The second writer is the agenda's creation form, in the app, which has no wall clock at all for an all-day event:

} else if (kind === 'event') {
  all_day = allDay;
  let start = dateValue;
  if (!allDay) {
    // ... apply the typed hour
  } else {
    start = new Date(dateValue);
    start.setHours(0, 0, 0, 0);
  }
  due_at = start.toISOString();

This is JavaScript's contribution. There is no date-only type; the closest thing is a Date at local midnight, and toISOString() serializes it in UTC. On a phone ahead of UTC, "Friday" leaves the device as Thursday 22:00Z. Same instant as the first writer, by a different road.

The third writer is the import from the phone's calendar, and here the platform has an opinion. Android's calendar provider stores an all-day event at UTC midnight, with an exclusive end: the midnight after the last day, as in iCalendar. The app's mapper knew it:

function wallHours(start: number, end: number, allDay: boolean) {
  if (allDay) {
    // Android stores all-day bounds at UTC midnight ; the UTC date IS the
    // civil day, and dtend is exclusive (the midnight after the last day).
    const lastDay = utcDay(Math.max(start, end - DAY));
    return { start_local: `${utcDay(start)}T00:00`, end_local: `${lastDay}T23:59` };
  }
  return { start_local: localTimestampToWall(new Date(start)), end_local: localTimestampToWall(new Date(end)) };
}

Those wall clocks are correct. But the server stored the raw provider instants next to them (due_at: upcoming.start, end_at: upcoming.end), so the row ran from Friday 00:00Z to Saturday 00:00Z, exclusive end kept. And whenever the phone reported its timezone, a recompute job re-derived every future row from its wall clock in that zone, which moved imported all-day rows back onto Thursday evening.

The readers had already agreed

What makes this bug instructive: the code that READ all-day rows was consistent. It had been fixed after an earlier incident, and it walks all-day rows in UTC. The morning briefing's day filter, in recapSnapshot.ts:

function coversDay(n: RecapNeuron, day: string, tz: string): boolean {
  if (!n.due_at) return false;
  const zone = n.all_day ? 'UTC' : tz;
  const start = localDateOf(n.due_at, zone);
  const end = n.end_at ? localDateOf(n.end_at, zone) : start;
  return start <= day && day <= end;
}

The app's agenda does the same in agendaDates.coveredDayKeys, and the write-back to the phone's calendar puts all-day bounds on UTC midnight too. Three readers, one convention: an all-day row sits on 00:00Z of its first day and 23:59Z of its last.

The writers had never been told. Feed their rows to those readers, briefing at 08:00 local:

Row as written	Thursday briefing	Friday briefing	Saturday briefing	Rings at (local)
Dictated: Thu 22:00Z, no end	today	absent	absent	Fri 00:00
Form: Thu 22:00Z, no wall clock	today	absent	absent	Fri 00:00
Imported: Fri 00:00Z to Sat 00:00Z	absent	today	today	Fri 00:00 on the phone, 02:00 from the server

The first two lines are the report. The reminder rang at midnight on Friday in the owner's zone: the right day. The briefing read the same instant in UTC and saw Thursday. Each was right about its own rule. Nobody owned the rule for the row.

One convention, in one function

The fix writes the convention down once, in wallClock.ts:

export function allDayInstants(
  startWall: string,
  endWall: string | null | undefined
): { due_at: string; end_at: string; due_local: string; end_local: string } {
  const date = startWall.slice(0, 10);
  let endDate = endWall ? endWall.slice(0, 10) : date;
  if (endDate < date) endDate = date;
  return {
    due_local: `${date}T00:00`,
    end_local: `${endDate}T23:59`,
    due_at: `${date}T00:00:00.000Z`,
    end_at: `${endDate}T23:59:00.000Z`
  };
}

No Date, no zone, no arithmetic: the date part of a wall clock in, strings out. Every earlier bug came from turning the date into an instant too early, so this function never does.

Then every writer goes through it. deriveInstants gains a branch:

  if (input.all_day === true) {
    const startWall = dueLocal ?? (input.due_at ? instantToWall(input.due_at, timezone) : null);
    if (startWall) {
      const endWall = endLocal ?? (input.end_at ? instantToWall(input.end_at, timezone) : null);
      return allDayInstants(startWall, endWall);
    }
  }

The second line handles the form without touching the app. An old build still sends Thursday 22:00Z; the server reads it back as a wall clock in the owner's zone, gets Friday 00:00, and keeps only the date. The test pins that road (TZ is two hours ahead of UTC in September):

test('an all-day fiche sent as the form local-midnight instant lands on that civil day, not the day before', () => {
  // The agenda form sends new Date(day).setHours(0), which is 22:00Z the evening before.
  const out = deriveInstants({ due_at: '2026-09-10T22:00:00.000Z', all_day: true }, TZ);
  assert.equal(out.due_at, '2026-09-11T00:00:00.000Z');
  assert.equal(out.end_at, '2026-09-11T23:59:00.000Z');
  assert.equal(out.due_local, '2026-09-11T00:00');
});

The recompute job now ignores the zone for all-day rows. The import drops Android's exclusive end:

  // The phone sends Android's exclusive next-midnight end for an all-day
  // event ; the agenda wants 23:59Z of the LAST day (allDayInstants).
  const bounds = entry.all_day
    ? allDayInstants(upcoming.start_local, upcoming.end_local)
    : { due_at: upcoming.start, end_at: upcoming.end, due_local: upcoming.start_local, end_local: upcoming.end_local };

The cron that moves a yearly event to its next occurrence uses it too. Four writers, one function, with tests on the derivation, the recompute and the import (the yearly re-arm has none).

The fix that rang at two in the morning

Two hours later, the next commit. Anchoring the row on Friday 00:00Z fixed every reader asking "which day does this cover?" and broke the one asking "when do I ring?". The reminder cron rang at due_at, and Friday 00:00Z is 02:00 two hours ahead of UTC. Four hours behind UTC, it is 20:00 on Thursday.

An all-day row answers two questions, and they need two rules. The day it covers is a date, the same everywhere. The moment it rings is an hour in the owner's life, in the owner's zone. The product already had an hour meaning "start of my day": the time the morning briefing is delivered, a setting. So reminderRingInstant.ts:

export function allDayRingWall(dueLocal: string, hour: number, minute: number): string {
  return `${dueLocal.slice(0, 10)}T${pad(hour)}:${pad(minute)}`;
}

export function ringInstantMs(neuron: RingSource, settings: RingSettings): number {
  if (neuron.all_day && isWallFormat(neuron.due_local)) {
    const wall = allDayRingWall(neuron.due_local, settings.briefing_hour, settings.briefing_minute);
    return wallToInstant(wall, settings.timezone).getTime();
  }
  return new Date(neuron.due_at).getTime();
}

The civil date from the anchor, the hour from the settings, the zone conversion last. Lead times count back from that instant, so "the day before" rings Thursday at the briefing hour, not Thursday at 02:00. The tests use real offsets, including the one that moves:

test('the briefing hour and minute are the owner setting, not a constant', () => {
  const ms = ringInstantMs(
    { due_at: '2026-12-10T00:00:00.000Z', due_local: '2026-12-10T00:00', all_day: true },
    { timezone: TZ, briefing_hour: 7, briefing_minute: 30 }
  );
  // Winter time : 07:30 local = 06:30Z.
  assert.equal(new Date(ms).toISOString(), '2026-12-10T06:30:00.000Z');
});

The server is only half the delivery. Reminders ring through a local alarm scheduled on the phone (it works offline), with the server push as a safety net, so the app got a mirror, allDayRing.ts, same function, same name, used by LocalReminderService:

  if (neuron.all_day && isWallFormat(neuron.due_local)) {
    const prefs = await getPrefs();
    ts = wallToLocalTimestamp(allDayRingWall(neuron.due_local, prefs.briefing_hour, prefs.briefing_minute));
  } else {
    ts = isWallFormat(neuron.due_local) ? wallToLocalTimestamp(neuron.due_local) : new Date(neuron.due_at).getTime();
  }

Repairing the rows without shipping an app

Fixed writers correct the rows written from now on. The rows already stored were still on Thursday evening, and no reader can tell which convention wrote a row. So the repair is a pass in the backfill that already runs at every server boot:

  // Second pass : all-day rows written under the old derivation [...] are
  // pinned to the agenda's UTC anchors. Idempotent : a row already on the
  // convention is not touched.
  for (const row of await deps.listFutureAllDay(nowIso)) {
    if (!row.due_local) continue;
    const day = allDayInstants(row.due_local, row.end_local);
    if (day.due_at === row.due_at && day.end_at === row.end_at) continue;
    await deps.updateRow(row.id, { due_at: day.due_at, end_at: day.end_at, due_local: day.due_local, end_local: day.end_local });
    moved++;
  }

With its read:

      const { data, error } = await client
        .from('neurons')
        .select('id, due_at, end_at, due_local, end_local')
        .eq('status', 'active')
        .eq('all_day', true)
        .not('due_local', 'is', null)
        .gte('due_at', nowIso)
        .limit(5000);

It rebuilds from due_local, the owner's words, never from the instant it repairs. It only touches the future: a past event belongs to history. And it calls the same function as the writers, so a repaired row holds exactly what a fresh write holds.

Because the repair and the readers live on the server, the agenda, the briefing and the backup push were right after the next boot, on every installed version of the app. The phone's local alarm is the exception: that code ships inside the app, and an older build still rings an all-day event at local midnight until it is updated. On the right day, which the repaired row guarantees; the hour needs the release.

What the code does not prove

That comment said idempotent, and the tests agreed, because their fixtures held '2026-09-11T00:00:00.000Z'. The database client hands the same instant back as '2026-09-11T00:00:00+00:00'. Two strings for one instant: the skip never fired in production, each boot rewrote identical values, and the update trigger moved updated_at on every future all-day row. The live table showed exactly that. The values were right; the guarantee was not. The recompute job compared the same way.

I found it while writing this article, and the fix went in on 10/09/2026. Both guards now compare instants, not their spelling, and the tests use the shape the database really returns:

export function sameInstant(a: string | null | undefined, b: string | null | undefined): boolean {
  if (a == null || b == null) return a == null && b == null;
  if (a === b) return true;
  const ta = Date.parse(a);
  const tb = Date.parse(b);
  return !Number.isNaN(ta) && ta === tb;
}

The backfill skips rows without a wall clock, and a row from the old form has none. In the live table no future all-day row lacked one, so nothing is stranded today; that is a fact about the data, not a property of the code.

The query that fetches a day's rows still builds its window on the owner's wall clock, so a UTC-anchored row can be fetched for one boundary day too many. A comment calls this deliberate (both renderers re-filter on calendar days), but it is a second convention living next to the first.

The lesson I kept: a date without an hour is not a midnight. Store the day as a day, and let each question build its own instant at the last moment. "Which days does it cover" needs no zone; "when does it ring" needs the owner's zone and the owner's idea of morning. Then grep for every writer, because readers get fixed after incidents and writers get forgotten.

Thanks to the tester who noticed that the phone and the briefing disagreed about today; reports like that are what move XNeuronal forward. The agenda described here ships in the Android app at xneuronal.com.

The app that spoke German but titled everything in French: the language of a system prompt is a parameter, not a constant

XNeuronal — Wed, 09 Sep 2026 06:29:12 +0000

A German user posted a screenshot on an Android forum. His interface was in German, his conversations with the assistant were in German, and the panel listing his past conversations was in French. Every title. A conversation held entirely in German about a trip planned for the next day was listed as "voyage pour demain", and he was politely asking whether his notifications had switched back to French on their own.

They had not. The titles had never been in German. XNeuronal ships in six languages, the assistant answers in the language you set, and one small side prompt had been quietly writing French into every account since the day it was born. This is the story of that bug, of the three siblings it turned out to have, and of the data repair that followed. It was fixed on 08/09/2026, in one backend commit. A Node backend in TypeScript, every block below copied from the repository and lightly trimmed.

Where the French came from

When a conversation ends, an archiver stores it, then asks the model for a four-to-six word title to show in a list. Here is the instruction it sent, the same for every account, as it stood before the fix:

const prompt: LLMMessage[] = [
  {
    role: 'system',
    content:
      "Résume en 4 à 6 mots ce dont on a discuté. Ton résumé sert de titre dans une liste. " +
      "Pas de phrase complète, pas de ponctuation finale. Exemples : " +
      "'recettes de pâtes carbonara', 'rdv dentiste & déménagement', 'voisin marc & courses'."
  },
  { role: 'user', content: transcript }
];

A French instruction, French examples, and no word about which language the answer should be in. The transcript underneath was German. The model did the only sensible thing a French instruction with French examples allows: it answered in French.

That is the first lesson, and it is not about this model or that one. A model answers in the language of the instruction, not in the language of the content. If the system prompt is in French, the "obvious" language of the task is French, whatever the user message contains. When you write your prompts in your own language, the default is invisible to you, because it is also the language you test in. The bug shipped because the developer speaks French.

The fix, part one: the language becomes an argument

The backend already had a single registry of the languages it supports, used by the main conversation prompt, the transcription hints and the push texts:

export const SUPPORTED_LANGUAGES = ['fr', 'en', 'de', 'es', 'it', 'pt'] as const;
export type SupportedLanguage = (typeof SUPPORTED_LANGUAGES)[number];

/** Native display names, used in the LLM output-language directive. */
export const LANGUAGE_NATIVE_NAMES: Record<SupportedLanguage, string> = {
  fr: 'français', en: 'English', de: 'Deutsch', es: 'español', it: 'italiano', pt: 'português europeu'
};

The side prompts simply did not use it. They now live in one file, i18n/languagePrompts.ts, and every one of them takes a language:

export function conversationTitleInstruction(language: SupportedLanguage): string {
  const native = LANGUAGE_NATIVE_NAMES[language];
  return (
    'Summarize in 4 to 6 words what the conversation was about. The summary is used as a title ' +
    'in a list of past conversations. No full sentence, no final punctuation, no quotes. ' +
    `Write the title in ${native}, whatever language the transcript is in. ` +
    'Keep proper nouns (people, places) as they are written.'
  );
}

Three choices in there, each deliberate.

The carrier language is English. Not because English is special, but because the instruction must no longer suggest an answer language by its own form; the explicit directive has to be the only signal, and English is the language the models follow most reliably for meta-instructions.

The target language is named in its native form ("Deutsch", not "German"), which is what the models latch onto with the fewest surprises.

And "whatever language the transcript is in" is there on purpose. A German owner who dictates a French sentence still reads the title in a German list. The language of a title belongs to the interface it appears in, not to the content it summarizes.

The archiver itself changed in two ways. It now reads the owner's language from the settings table, through an injected dependency so the tests never touch the database, and it exposes the title computation without the write, because a repair script was going to need it:

export interface ArchiverSettings {
  getLanguage(ctx: AuthContext): Promise<SupportedLanguage>;
}

async titleFor(conv: ArchivableConversation, auth: AuthContext): Promise<string> {
  const language = await this.ownerLanguage(auth);
  return this.summarize(extractTurns(conv.history), language);
}

/** Defensive read : a settings hiccup must cost the language, never the title. */
private async ownerLanguage(auth: AuthContext): Promise<SupportedLanguage> {
  try {
    return asSupportedLanguage(await this.settings.getLanguage(auth));
  } catch (err) {
    console.warn('[archiver] language lookup failed, titling in French:', ...);
    return 'fr';
  }
}

The fallback deserves a sentence. The archiver runs after the conversation is over, and a title is a nicety. If the settings read fails, the worst acceptable outcome is a French title, the old defect for one conversation. Failing the archive would be a new defect introduced by the fix.

The fix, part two: a broken contract gets fixed on every path

Once you know the shape of the bug, "a French instruction sent to a model", you grep for it. The grep came back with three more hits, and this is the part I want to insist on, because it is where fixes usually stop short.

The first two were the attachment reader. When a user attaches a photo or a document, a vision prompt transcribes it and a summary prompt condenses it, both in French, with an explicit "Réponds en français" this time. Worse, the code building those prompts existed twice, copied and pasted: once in the upload-time extraction, once in the read_attachment tool the assistant calls mid-conversation. Fixing one copy would have given a German owner a German transcript on upload and a French one when asking for the same file read aloud.

Both copies were replaced by one factory:

export function buildReaderDeps(engines: ReaderEngines, language: SupportedLanguage): ReaderDeps {
  const prompts = attachmentReaderPrompts(language);
  return {
    transcribe: (bytes, mime) =>
      engines.stt.transcribe(bytes, `attachment.${mime.split('/')[1] ?? 'm4a'}`, {}).then((r) => r.text),
    ocrImage: (bytes, mime) => engines.llm.visionDescribe(bytes, mime, prompts.ocr),
    summarize: (text) =>
      engines.llm.chat([
        { role: 'system', content: prompts.summarize },
        { role: 'user', content: text }
      ])
  };
}

The upload path calls it with the language of the row's owner; the tool handler calls it with the language of the authenticated caller. Same engines, same prompts, one place to be wrong.

The third sibling was subtler because it was not a text output. The speech synthesis has a primary engine and a fallback engine, and the fallback accepts a free-text tone hint. That hint was a single French constant, exported from the fallback's module and imported by the conversation loop and two REST endpoints: "speak natural French, no foreign accent, warm and calm", sent for every language. A German owner who hit the fallback heard his German text read with a French accent. Nobody noticed, because the fallback rarely fires and the developer is French.

The constant is gone. In its place, one hint per supported language, keyed on the same registry:

const HINTS: Record<SupportedLanguage, string> = {
  fr: 'Parle en français naturel, sans accent étranger. Ton chaleureux, posé, légèrement complice.',
  en: 'Speak natural English, without a foreign accent. Warm, calm tone, slightly complicit.',
  de: 'Sprich natürliches Deutsch, ohne fremden Akzent. Warmer, ruhiger Ton, leicht vertraut.',
  // es, it, pt ...
};

export function ttsInstructionsFor(language: unknown): string {
  return HINTS[asSupportedLanguage(language)];
}

Deleting the constant rather than renaming it is the point. A removed export cannot be re-imported by the next person who needs "the TTS instructions"; the compiler sends them to the function that asks for a language.

That last path forced a small structural change. The conversation loop already resolves the owner's language on every turn. The two REST endpoints did not: their guard decided whether the request was allowed and returned a boolean. It now returns the caller's identity, so the route can look up a language before synthesizing. Fixing a contract on every path sometimes means giving a path information it never needed before.

Testing a prompt without calling a model

None of the new tests call a model. They assert on the prompt that would be sent, captured by a fake:

test('enrich asks the title in the owner language read from the settings', async () => {
  const { archiver, prompts } = makeArchiverWithLanguage('de');
  await archiver.enrich('row-1', 'n1', conv([
    { role: 'user', text: 'Reise nach Lübeck morgen' }, { role: 'assistant', text: 'Notiert.' }
  ]), auth);
  assert.equal(prompts.length, 1);
  assert.match(prompts[0], /Deutsch/);
  assert.doesNotMatch(prompts[0], /Résume|français/);
});

The negative assertion is the one that matters. /Deutsch/ proves the directive is there; /Résume|français/ proves the old French wording is not, which is exactly the regression a well-meaning refactor would reintroduce ("let me put the examples back, they helped").

A second test loops over the whole registry:

test('conversationTitleInstruction covers every supported language with its native name', () => {
  for (const lang of SUPPORTED_LANGUAGES) {
    assert.match(conversationTitleInstruction(lang), new RegExp(LANGUAGE_NATIVE_NAMES[lang]));
  }
});

Together with Record<SupportedLanguage, string> on the hint tables, this means adding a seventh language to the registry fails at compile time until every table has an entry, and fails at test time until every prompt names it. The registry is the contract; the tests are what stop a path from silently opting out of it.

The third kind of test pins the fallback: the settings dependency throws, and the prompt must still be French, not an unhandled rejection. Defensive code that is not tested is a promise, not a behaviour.

Repairing what was already written

Fixing the code corrects every conversation archived from now on. The screenshot was about conversations archived last week, and those rows stay wrong forever unless something rewrites them. So the commit ships a script, scripts/retitleConversations.ts, and its design is the fourth lesson.

It is a dry run by default. --apply writes; nothing else does. --language de and --owner <id> narrow the scope. And it does not re-express the write in SQL: it calls the archiver's own enrich(), the tested implementation that updates the index record, its embedding and the conversation summary together, so repaired rows are indistinguishable from freshly archived ones. titleFor() exists so the dry run can show what would be written without writing it:

if (!apply) {
  const title = await archiver.titleFor(snapshot, auth);
  console.log(`  ${row.id.slice(0, 8)}  "${row.summary}"  ->  "${title}"`);
  continue;
}
if (index) {
  await archiver.enrich(row.id, index.id, snapshot, auth);
} else {
  await conversationService.updateSummary(row.id, await archiver.titleFor(snapshot, auth));
}

Two decisions about scope. The script only selects owners whose language is not French, because French titles for French owners are correct, and re-titling them would change text people have already seen for no reason. Do not touch what is already right, even when touching it would be harmless. And it handles the row without an index record (older conversations predate that record), because a repair script that throws on the first odd row leaves the data in a state nobody planned for.

On idempotence, honestly: running it twice asks the model twice and may produce a slightly different title the second time. The write is stable in shape, not byte for byte. What makes it safe to re-run is the scope selection, not the write; a weaker guarantee than true idempotence, and worth knowing before you type --apply a second time.

The dry run in production listed about a dozen conversations across a handful of non-French accounts. The ones belonging to the user who reported the bug came back in German, and he could see it by simply reopening the list. The apply pass was run by a human with production credentials, after reading the dry run line by line, which is how this kind of script should always be run.

What I would do differently

The grep found the siblings, but a grep is a one-off. The durable version is a rule the code can enforce: no literal prompt string outside the i18n directory, checked by a test that scans the source tree for French wording next to a role: 'system'. We did not write that test. Until we do, the next French prompt will be caught by a German user again.

The language is now looked up separately in four places (archiver, upload extraction, tool handler, REST routes), each with its own defensive fallback. It should be a field of the request context, resolved once with the identity and passed down. Four correct lookups are still four places to forget one.

The examples in the old prompt were useful, and the new one has none, because examples in one language are exactly the signal we were trying to remove. Per-language examples would beat no examples, and they are one more table keyed on the registry.

And the one that costs nothing: test the product in a language you do not speak. Every one of these four paths behaved perfectly in French. The defect was only visible from a phone set to German, held by someone kind enough to send a screenshot.

Making a killed app speak: high-priority FCM, headless JS, and the service that buys a voice its right to talk

XNeuronal — Tue, 08 Sep 2026 09:56:33 +0000

In XNeuronal, the server composes a short spoken briefing in the morning ("two things today, and the rain arrives at four") and pushes it to the phone. While the app is open, that is easy: a WebSocket frame arrives, the client fetches the audio, the assistant talks. The feature only earns its keep in the opposite situation, a phone lying on a table, screen off, app swiped away. Making that phone speak turned out to involve four Android mechanisms, two field-reported bugs, and one manifest line whose absence breaks nothing at build time and everything at runtime.

React Native 0.81, a Node backend, one hand-written Kotlin module. Every block below is copied from the repository at the commit named above it, lightly trimmed.

One message, three deliveries

The backend does not trust any single channel. A proactive message is written to an inbox table (the durable copy), pushed over the live WebSocket (the app-open copy), and sent through FCM (the app-closed copy).

backend/src/services/proactivity/ProactivityCron.ts at 7eb56ec:

  /** Triple delivery : inbox row + live WS + FCM (authenticated only). */
  private async deliver(owner, kind, content, title, metadata): Promise<void> {
    await inboxService
      .push({ user_id: owner.user_id, device_id: owner.device_id, kind, content, metadata })
      .catch((err) => console.warn('[proactivity-cron] inbox push failed:', err));

    notifyOwner(owner, { type: 'inbox_event', kind, content });

    if (!owner.user_id) return; // anonymous → no FCM token
    await fcmService
      .sendToUser(owner.user_id, {
        title,
        body: pushBody(content),
        data: {
          kind,
          proactive: '1',
          body_full: content.length > 1500 ? `${content.slice(0, 1500)}…` : content
        }
      })
      .catch((err) => console.warn('[proactivity-cron] fcm failed:', err));
  }

The FCM message is the interesting one, because it is a hybrid. The classic tutorial choice is "notification message OR data message". This is both, on purpose. The notification block means Android displays the tray line by itself, with zero app code, even if everything below fails; the OS notification is the floor, the voice is the bonus. The data block carries proactive: '1', the marker every later gate keys on, and body_full, because the body the OS shows is truncated for a one-line tray entry and you do not want the voice to read an ellipsis.

The send itself sets android: { priority: 'high' } (in FCMService.sendToTokens, same repo). Without high priority, a device in Doze batches the delivery for the next maintenance window and your "morning" briefing arrives whenever Android feels like it; with it, the OS wakes the device and runs the app's background handler on arrival. That handler is the whole trick.

The headless entry point

react-native-firebase lets you register a handler that runs when a push arrives with the app backgrounded or killed. On Android, "killed" means the OS spins up a fresh headless JavaScript context just for this function.

frontend/index.js at 7a0a6ba:

messaging().setBackgroundMessageHandler(async (message) => {
  await Promise.all([
    LocalReminderService.dedupeAgainstFcm(message?.data),
    handleBackgroundReadAloud(message)
  ]);
});

Two jobs, both best-effort, neither allowed to reject. The first clears a redundant tray copy when a reminder already rang locally. The second is the voice.

Five gates before a word comes out

frontend/src/services/BackgroundReadAloud.ts at 70b1ad4:

export async function handleBackgroundReadAloud(message): Promise<void> {
  try {
    const text = voiceableText(message);
    if (!text) return;

    const prefs = await getPrefs();
    if (!prefs.proactivity_enabled || !prefs.read_aloud || !prefs.read_aloud_background) return;
    if (inLocalQuietHours(prefs)) return;

    if (wasRecentlySpoken(text)) return;
    markSpokenAloud(text);

    await speakProactive(text);
  } catch (err) {
    console.warn('[background-read-aloud] failed:', err instanceof Error ? err.message : err);
  }
}

Each line is a lesson paid for.

voiceableText only accepts pushes stamped proactive: '1'. Reminder pushes are deliberately silent here, and the file's header comment records why: a field report of a reminder that rang as an alarm AND was then read aloud, because the backend sends a safety-net FCM copy of every reminder the phone also schedules locally. A message the user asked for already has its own delivery; voicing the backup copy is a second alert, not a service.

read_aloud_background is a dedicated toggle ("even when the app is closed"), default OFF. Speaking out of a pocket is the kind of surprise that gets an app uninstalled; it has to be asked for.

inLocalQuietHours re-checks quiet hours on the device clock even though the backend already withholds proactive sends during the configured window. The server knows one timezone; the phone may be sitting in another.

And the wasRecentlySpoken pair guards against a subtle double delivery: when the app is backgrounded but still alive, the same message arrives through the WebSocket (the app-open path) and through FCM, in the same JavaScript context, seconds apart. Whoever speaks first stamps the text into a TTL map (three minutes, keyed on the normalized full text) and the other path finds it there.

The voice is a server round-trip

There is no on-device TTS in this path. The assistant has a chosen voice, and the briefing must sound like the assistant, so the headless task calls the same endpoint the live conversation uses.

frontend/src/services/InboxService.ts at dace638:

export async function speakText(text: string): Promise<void> {
  const clean = text.trim();
  if (!clean) return;
  const headers = { ...(await authHeaders()), 'Content-Type': 'application/json' };
  const voice = await getVoice().catch(() => undefined);
  const ttsRes = await fetch(`${env.backendHttpUrl}/tts/speak`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ text: clean, voice })
  });
  if (!ttsRes.ok) throw new Error(...);
  const ttsBody = (await ttsRes.json()) as { audioBase64?: string };
  if (!ttsBody.audioBase64) throw new Error(...);
  await ttsService.play(ttsBody.audioBase64);
}

Base64 audio over authenticated HTTPS, played locally. Server side, that endpoint fronts a primary/fallback synthesis pair, so the voice heard app-closed is byte-for-byte the conversation voice. The cost is honest: no network, no readout. The tray notification still landed, which is why the hybrid message shape matters.

The phone that was busy

The first shipped version spoke the moment the push arrived. The push arrives at a fixed hour; the phone alone knows whether that hour is a good moment. A briefing that talks over a phone call is worse than none.

So every readout now goes through a gate, frontend/src/services/SpeechGate.ts at 7a0a6ba:

export async function speakProactive(text: string, hooks?: SpeechHooks): Promise<void> {
  const clean = text.trim();
  if (!clean) return;
  const now = Date.now();
  dropExpired(now);
  if (queue.some((entry) => entry.text === clean)) return;
  if (hooks) hooksByText.set(clean, hooks);

  const entry: Pending = { text: clean, expiresAt: now + WAIT_WINDOW_MS };
  if (!(await lineTaken())) {
    await attempt(entry);
    return;
  }
  await enqueue(entry);
}

lineTaken asks a small Kotlin module two questions off AudioManager, no permission needed: is a call (or VoIP conversation) in progress, is other audio playing. The rule in that module is written at the top of the file: when in doubt, speak. A missing module, a throwing bridge, an unknown platform all answer "free", because an app gone mute from a defensive check is a broken feature, while occasional over-talking is merely the old behaviour.

A busy phone puts the text in a disk-backed queue with a two-hour expiry (a morning recap read at noon makes no sense), then a 5-second poll waits for the line to free up, plus a 30-second courtesy delay so the voice does not start the instant a call ends. The function resolves as soon as the decision is made, never at the end of the wait: a headless task cannot be kept alive for the length of a phone call.

The preference and quiet-hours checks run again at speaking time inside attempt(), not just at queueing time, because a message may have waited an hour and the world has moved on; a digest held back by a call must not wake up inside the silent window.

And the queue is emptied through an exclusive() mutex, added after a field report worth quoting from the comment: reopening the app fired two drain passes 21 milliseconds apart (screen mount, then the app turning "active"), and the same recap was read two or three times on top of itself.

The right to speak at all

This is the part that will bite anyone building background audio in 2026. Since Android 15, the OS refuses audio focus to an app that is neither visible nor running a foreground service. Android 17 goes further: the playback itself fails, silently, in that state. Google leaves one door open, a foreground service that is not of type SHORT_SERVICE.

So the readout runs inside a mediaPlayback foreground service, and the service is claimed at a precise moment: when the message is queued, not when it is finally spoken. The comment in enqueue() explains the economics:

  // Claim the foreground service NOW : the push that brought this message is
  // what grants the right to start one, and that right expires. Twenty minutes
  // later, when the call ends and the poll picks the message up, nothing could
  // hand it back.
  await holdSpeechForegroundService();

A high-priority FCM push is an official exemption that allows starting a foreground service from the background, and it does not last. Background rights on Android are a currency handed out at specific moments; you spend them when they exist, not when you need them.

Two manifest lines carry the rest. frontend/android/app/src/main/AndroidManifest.xml at 7a0a6ba:

      <service
        android:name="app.notifee.core.ForegroundService"
        android:foregroundServiceType="mediaPlayback"
        tools:replace="android:foregroundServiceType" />

      <service
        android:name=".SpeechRetryService"
        android:exported="false" />

The first overrides notifee's own declaration: the library ships its foreground service declared as shortService, the one type the new rule excludes. Removing that line does not break a build; it makes the voice go silent on the next Android version.

The second exists because of the best bug of the chantier. A held-back message must survive the app being swiped away, so a WorkManager job re-wakes a headless task later to drain the disk queue. The service that task runs in was missing from the manifest until one release, and startService() on an undeclared component returns null WITHOUT throwing. The worker logged its wake-up, reported success, and had started nothing. Silence, with green logs.

What the code does not prove

The anonymous mode gets none of this: deliver() returns before the FCM send when there is no user_id, so only signed-in users hear briefings app-closed.

The dedup map lives in memory, per JavaScript context. It covers the real double-delivery case (WS and FCM landing in the same living context); a context that dies between the two would forget, and the disk queue's own by-text check is what catches that. No test pins the boundary between the two guards.

Nothing tests the actual Doze wake, the Android 17 playback refusal, or an OEM task killer. Xiaomi-class "battery savers" can suppress headless JS entirely, and the code's answer to that is the tray notification, not the voice. The Android 17 claim is taken from documented platform behaviour, not from a device running it.

And body_full is truncated at 1500 characters with an ellipsis to stay under FCM's 4 KB data budget, which means a runaway briefing would be read aloud mid-sentence. The cap has never been hit; the guard is there for the day the composer misbehaves.

The lesson I kept: on modern Android, "can my app do X in the background" is the wrong question. The right one is "which event currently grants me the right to do X, and how long does the grant last". A high-priority push grants a foreground service start; a foreground service grants audio focus; audio focus grants a clean cut-off if a call starts mid-sentence. Chain the grants at the moment each exists, write down which failure each guard was bought by, and let the OS notification be the floor that survives when any link breaks.

An offline edit queue that can undo itself: rollback payloads, a lock, and the rule we had to delete

XNeuronal — Tue, 01 Sep 2026 10:27:47 +0000

The app keeps a person's notes and lists on a server, and the server is the only source of truth. The phone holds a read-only mirror, refreshed on every successful fetch and served only when the network fails. That rule is easy to keep for reads. It gets uncomfortable the first time someone ticks an item on a list in a shop with no signal: the screen has to obey now, the server hears about it later, and in between the phone is showing a state nobody has accepted.

This is the write side of that design: a durable queue of edits made without a connection, replayed by two triggers, able to undo itself when the server says no. React Native 0.81, one Kotlin module. Every block below is copied from the repository at the commit named above it.

An entry that remembers what it replaced

The queue is a JSON array in AsyncStorage, and the shape of one entry is the whole design.

frontend/src/services/pendingEditGuards.ts at e4fbb70:

export interface PendingEdit {
  id: string;
  neuronId: string;
  /** The fields to send, exactly as the PATCH body. Empty for a deletion. */
  patch: Record<string, unknown>;
  /** Those same fields as they were BEFORE the edit. Without this a rollback
   *  is impossible: we would know to undo without knowing what to restore.
   *  For a deletion this holds the WHOLE fiche, since that is what a rollback
   *  has to put back. */
  previous: Record<string, unknown>;

patch is the request body, verbatim. previous is the same keys as they stood in the local mirror before the edit, an absent field recorded as null so that rolling back clears it. A deletion carries an empty patch and the entire cached row as previous.

An optional kind field marks deletions and favourites. Optional on purpose: the first shipped version only knew patches, and entries already sitting on phones had to stay valid across the update. An unknown kind is dropped at parse time rather than replayed as the wrong request.

Send first, queue on transport failure

Every writer goes through one function. It tries the network, and only a retryable failure sends the edit to the queue.

frontend/src/services/MemoryService.ts at cae57e0:

  try {
    await sendNeuronPatch(id, patch);
    void neuronCache.patch(id, patch).catch(() => {});
    return;
  } catch (err) {
    // An explicit refusal is not an offline case: it must reach the user now.
    if (!isRetryable(err)) throw err;
    const cached = await neuronCache.get(id).catch(() => null);
    await pendingEdits.enqueue({ neuronId: id, patch, previous: previousOf(cached, patch) });
    void neuronCache.patch(id, patch).catch(() => {});
  }

isRetryable is a regex over the error message: a 400, 403, 404 or 409 is definitive, everything else is worth another try. A 409 in particular means the server's own merge-and-retry already gave up. If the server says no while the network is fine, the user needs to see that now, not at the next reconnect.

Status changes ("done", "archived") ride the same path. Deletions joined it later the same day, the last gesture of the card menu still doing a bare DELETE and throwing with no signal.

The rule that had to go

The first version of the queue refused shared cards. The reasoning was in the guard itself.

frontend/src/services/pendingEditGuards.ts at 7d688f9:

export function isSharedFiche(neuron: Record<string, unknown> | null): boolean {
  if (!neuron) return true;
  if (neuron.visibility === 'shared') return true;
  const meta = neuron.metadata as { shared_ref?: unknown } | null | undefined;
  return Boolean(meta?.shared_ref);
}

A card with more than one author, the argument went, could have a friend's tick erased by a stale edit replayed hours later. An unknown card counted as shared, because refusing one edit was cheaper than overwriting someone. It was cautious, it was tested, and it was wrong twice over.

First, the product: a shared grocery list ticked in a shop with no signal is the single most common offline moment the app has. Refusing it broke exactly what offline mode exists for. Second, the server already provided the protection.

backend/src/routes/anonymous.ts at cae57e0:

    if (attemptNo > 0) {
      const { data: fresh } = await serviceClient
        .from('neurons')
        .select('metadata,updated_at')
        .eq('id', req.params.id)
        .eq(column, value)
        .maybeSingle<{ metadata: Record<string, unknown> | null; updated_at: string | null }>();
      if (!fresh) return { committed: true, value: { refusal: 'not_found' } };
      expectedUpdatedAt = fresh.updated_at;
      if (body.metadata !== undefined) {
        const merged = buildOwnerMetadata(
          body.metadata as Record<string, unknown>,
          (fresh.metadata ?? {}) as Record<string, unknown>,
          userId ?? deviceId ?? 'owner',
          new Date().toISOString(),
          body.removed_section_ids,
        );
        if (!merged.ok) return { committed: true, value: { refusal: merged.error } };
        effectivePatch = { ...patch, metadata: merged.metadata };
      }
    }

The PATCH route writes under an updated_at guard: the update carries .eq('updated_at', expectedUpdatedAt) and commits nothing if someone wrote in between. On that miss it re-reads the fresh row, merges the client's metadata onto it, and tries again. What the client imposes is reapplied; what the client never saw survives. Two people ticking different items both keep their tick. What the merge cannot save is a scalar rewritten on both sides, the card's text for instance: there, last writer wins and the card history keeps the trace.

So the guard was deleted at 3bc82c6, not left unused, because it encoded a rule that had just proved wrong. The same commit fixed something the refusal had hidden: no route returned visibility, so offline the "shared" badge vanished on a card a friend was editing.

Replay: order, refusal, rollback

Two triggers replay the queue: in the foreground the WebSocket connected frame, when the tube is known good; with the app closed, a native worker, described below. Both call the same flush(), which is why it holds a lock.

frontend/src/services/PendingEditStore.ts at e4fbb70:

  async flush(): Promise<void> {
    if (this.flushing) return;
    this.flushing = true;
    try {
      await this.replayOnce();
    } finally {
      this.flushing = false;
    }
  }

The lock arrived at bac42a8, after a test reproduced the failure: two overlapping passes read the same queue and sent the same edit twice. Harmless while a reconnecting socket was the only trigger; not once a background worker could start a pass while the user was opening the app. A plain flag is enough because both triggers share the JS context. The finally has a test of its own: a latching lock would drain the queue once and never again.

The pass walks the queue in arrival order. A retryable failure stops it and leaves the rest queued: two edits on the same card must land in the order they were made. A definitive refusal is where previous earns its place.

Same file, same commit:

        if (edit.kind === 'delete' && isDeleteAlreadySettled(err)) {
          await this.remove(edit.id);
          continue;
        }
        await this.remove(edit.id);
        if (Object.keys(edit.previous).length > 0) {
          await neuronCache.patch(edit.neuronId, edit.previous).catch(() => {});
        }
        const cached = await neuronCache.get(edit.neuronId).catch(() => null);
        const content = cached?.content;
        const title = typeof content === 'string' ? content.split('\n')[0].slice(0, 60) : '';
        this.onRejected?.({ neuronId: edit.neuronId, title });

The refused entry is dropped, the mirror is patched back to the pre-edit fields, and a handler set by the app names the card in a message to the user.

The first three lines are the one exception. A 404 counts as definitive, but a queued deletion answered 404 has already got what it wanted: the card is gone. Rolling that back would restore previous, the whole card, and resurrect something the user deleted. So a deletion treats 404 as success and drops the entry.

The second trigger, without the app

A card edited with no signal should reach the server without the app being reopened. On Android the queue reports its size to a small native module after every change; the module holds a single one-shot work item under a network constraint while the count is above zero and cancels it when the queue drains. ExistingWorkPolicy.KEEP means fifty offline edits arm one wake-up rather than fifty, and someone who never edits offline never asks the system for a single one.

frontend/android/app/src/main/java/com/xneuronal/OfflineReplayWorker.kt at 24cbb26:

  override fun doWork(): Result {
    val pending = OfflineReplayModule.pendingCount(applicationContext)
    if (pending <= 0) {
      Log.i(TAG, "nothing queued, not starting the replay")
      return Result.success()
    }
    return try {
      Log.i(TAG, "$pending queued, starting headless replay")
      applicationContext.startService(
          Intent(applicationContext, OfflineReplayService::class.java)
      )
      Result.success()
    } catch (err: Exception) {
      // Android refuses background service starts in some states. Retrying is
      // free and the constraint keeps it network-bound.
      Log.w(TAG, "could not start the replay service: ${err.message}")
      Result.retry()
    }
  }

Native learns how many entries wait, never which. The counter lets the worker skip booting a JavaScript runtime when the system fires the work after the app was reopened and the queue already drained. Otherwise it starts a headless task service, which runs the same flush() the foreground runs. The background replay inherits order, refusals, rollback and the 404-means-done rule by construction, not by discipline. A replay reimplemented in Kotlin would have been a twin that drifts, and drifting twins produced this project's worst defects.

frontend/index.js at 7a0a6ba:

AppRegistry.registerHeadlessTask('OfflineReplay', () => async () => {
  // Creations before edits: an edit aimed at a draft the server has never seen
  // takes a 404, and the edit queue reads a 404 as a definitive refusal - it
  // would roll back and destroy the fiche.
  const { pendingCreations } = require('./src/services/PendingCreationStore');
  const { pendingEdits } = require('./src/services/PendingEditStore');
  await pendingCreations.flush();
  await pendingEdits.flush();
});

The ordering comment describes a bug found by reading, not by a user. A card created offline has an id the server has never seen; an edit to it, replayed first, takes a 404, and 404 is definitive. Creations go first, on both triggers. The require() calls are deliberate too: the module graph must not be pulled in until the task runs, or a wake-up meant to flush a queue would boot half the app first.

The worker returns success without waiting for the JavaScript. If the replay fails, the queue keeps its entries and the next queue change arms a fresh wake-up. The queue is the only authority on what still has to be sent; the schedule is a hint to the OS, and its worst case is a wake-up that never fires, which is exactly where the app stood before the worker existed.

What the code does not prove

The unit tests cover the store on its real path: arrival order, a retryable failure leaving the rest queued, a rollback restoring the exact previous state, the lock refusing a second concurrent pass and accepting a later one, entries surviving a restart, a queued deletion answered 404 being dropped rather than resurrected. They run against mocked storage and mocked send functions. Nothing tests the Kotlin side: the counter, the KEEP policy, the network constraint, the headless service start. That the native worker and a foreground launch actually collide on a phone is inferred from the platform's documented behaviour, not from a captured trace.

The merge argument that justified deleting the shared-card guard rests on the server merging metadata, which is where checklist items live. A scalar field rewritten by two people offline is last-writer-wins by design, and no test pins what the second writer sees.

And the cap. The comment above MAX_ENTRIES says the oldest entries survive, because dropping the newest would discard what the user just did while they still believe it landed. The line beneath it is slice(-MAX_ENTRIES), which keeps the newest two hundred and drops the oldest. One of the two is wrong, no test pins which end goes, and nobody has hit the cap on a phone. I found that by copying the block for this article.

The lesson I kept: a client-side guard that refuses a write "to be safe" has to name the exact failure it prevents, and then someone has to check whether the server already prevents it. Ours did not survive that check, and keeping it had broken the product's most common offline moment.

The queue described here ships in the Android app at xneuronal.com.

Android geofences that never fired: a permission promise that lied, and a cache that outlived the OS

XNeuronal — Tue, 01 Sep 2026 08:08:58 +0000

A reminder tied to a place ("when I get home, take the bins out") is the one feature where you cannot poll. Waking the app every few minutes to read the GPS is exactly the battery profile Android punishes, and it is also unnecessary: Play services already runs a region monitor for every app on the device. You hand it a list of circles, it wakes a BroadcastReceiver when the phone crosses one, and your process does not exist in between.

That is the design that shipped: no foreground service, no location loop, an OS geofence per reminder. It was also silent, more than once, for unrelated reasons: no crash, no error, no notification. React Native 0.81 with a hand-written Kotlin module. Every block below is copied from the repository at the commit named above it.

The shape of the thing

The backend owns the reminders and exposes a projection: a list of {neuron_id, lat, lng, radius_m, direction, fallback_text}. A JS service fetches it on boot, on foreground, and whenever a socket frame says the set changed, then pushes the JSON to the native module. The Kotlin side removes the previous set and adds the new one.

frontend/android/app/src/main/java/com/xneuronal/GeofenceRegistrar.kt at ee55c2f:

    editor.apply()

    val client = LocationServices.getGeofencingClient(context)
    val pi = pendingIntent(context)
    client.removeGeofences(pi).addOnCompleteListener {
      if (geofences.isEmpty()) {
        Log.i(TAG, "register: set emptied (0 geofences monitored)")
        onResult(null, null)
        return@addOnCompleteListener
      }
      val request =
          GeofencingRequest.Builder()
              .setInitialTrigger(0)
              .addGeofences(geofences)
              .build()
      try {
        client
            .addGeofences(request, pi)
            .addOnSuccessListener {
              Log.i(TAG, "register: armed ${geofences.size} geofence(s)")
              onResult(null, null)
            }
            .addOnFailureListener { e ->
              Log.w(TAG, "register: addGeofences failed: ${e.message}")
              onResult("ADD_FAILED", e)
            }

Two details matter later. editor.apply() writes the full JSON and each reminder's fallback text to SharedPreferences before the client is touched, so the native side always holds the last intended set even if arming fails. And setInitialTrigger(0) disables the initial-enter trigger: arming a circle while already standing inside it fires nothing. Right for "remind me when I arrive", and a trap later on.

The Log.i lines are not decoration. In a release build, JS console.* never reaches logcat, so the XNGeofence tag was the only trace of the chain on a production phone.

Root cause one: the permission promise resolved before the user answered

Since Android 10, background location is its own permission. A geofence transition delivered while the app is not on screen requires ACCESS_BACKGROUND_LOCATION, and since Android 11 that permission has no runtime dialog at all: the request sends the user to the app's location settings page, where "Allow all the time" lives. So the flow has two steps, foreground then background, and the second only makes sense after the first succeeded.

The first version of the bridge did this.

frontend/android/app/src/main/java/com/xneuronal/GeofenceModule.kt at da86318:

  fun requestAlwaysPermission(promise: Promise) {
    if (!hasFine()) {
      reactApplicationContext.currentActivity?.let { activity ->
        ActivityCompat.requestPermissions(
            activity,
            arrayOf(Manifest.permission.ACCESS_FINE_LOCATION),
            REQ_CODE
        )
      }
      promise.resolve("denied")
      return
    }
    if (hasBackground()) {
      promise.resolve("granted")
      return
    }
    promise.resolve("needs_settings")
  }

ActivityCompat.requestPermissions is fire-and-forget; the answer arrives later in onRequestPermissionsResult. This method shows the foreground dialog and, on the very next line, tells JavaScript "denied" while the dialog is still on screen. The UI displayed its "you refused" step, the user tapped Allow in the system dialog behind it, the app got foreground location, and nobody ever asked for the background step, because from the JS side the flow had already failed. The reminder was persisted, geocoded and armed; the phone was simply not allowed to deliver it once the screen was off.

The rewrite goes through React Native's PermissionAwareActivity, whose requestPermissions takes a listener, and resolves the promise from inside it.

frontend/android/app/src/main/java/com/xneuronal/GeofenceModule.kt at ee55c2f:

  fun requestAlwaysPermission(promise: Promise) {
    if (hasBackground()) {
      promise.resolve("granted")
      return
    }
    val activity = reactApplicationContext.currentActivity as? PermissionAwareActivity
    if (activity == null) {
      // No activity to host a dialog (app not foregrounded). If fine is already
      // held the only remaining path is Settings, otherwise we can't ask.
      promise.resolve(if (hasFine()) "needs_settings" else "denied")
      return
    }
    if (!hasFine()) {
      requestFine(activity, promise)
    } else {
      requestBackground(activity, promise)
    }
  }

requestFine asks for foreground location and, on grant, posts requestBackground to the main looper rather than calling it directly: React Native clears the current permission listener after it returns true, so installing the next listener synchronously would get it nulled. requestBackground then issues the request that, on Android 11 and later, opens the settings page.

Same file, same commit:

    activity.requestPermissions(
        arrayOf(Manifest.permission.ACCESS_BACKGROUND_LOCATION),
        REQ_BG
    ) { requestCode, _, grantResults ->
      if (requestCode != REQ_BG) return@requestPermissions false
      val granted =
          grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED
      promise.resolve(if (granted) "granted" else "needs_settings")
      true
    }

A non-grant resolves needs_settings, not denied, because after repeated refusals the OS stops showing anything at all and the UI still needs a manual way to the settings page. The bug was a native method reporting an outcome it had not waited for, and a JS caller with no way to tell.

Root cause two: the app's cache survived what the OS forgot

With the permission fixed, reminders fired. Then one did not, with every permission granted, the reminder present in the projection, the phone in the circle. The device's location service dump showed no region registered for the app at all, and had shown none since a reboot two days earlier.

The JS sync kept a copy of the last set it had pushed in AsyncStorage, diffed the fresh projection against it, and skipped the native call when nothing had changed.

frontend/src/services/GeofencingService.ts at 67aac64:

  const current = await loadCurrent();
  const { toAdd, toRemove } = diffGeofences(current, next);

  // The owner has location reminders but hasn't granted "Always" yet → ask
  // the UI to run the disclosure + permission flow. A freshly added geofence
  // (toAdd) means the user just created a reminder : force the prompt so we
  // re-ask even if the session guard already fired. Passive boots respect it.
  if (next.length > 0) {
    const perm = await checkPermission();
    if (perm !== 'granted') {
      permissionPrompter?.({ force: Boolean(opts?.force) || toAdd.length > 0 });
    }
  }

  if (toAdd.length === 0 && toRemove.length === 0) return; // nothing changed

Reasonable, and wrong about what it was diffing against. The cache describes what JavaScript last asked for. The OS region set is what Play services currently monitors, and the two diverge on every device reboot and every app update, both of which drop registered geofences while AsyncStorage survives untouched. After a reboot the cache said "all armed", the projection said "same reminders", the diff said "nothing to do", and every later sync agreed. The set stayed empty until a reminder was created or deleted, which could be never.

The fix is the boring one: the diff may no longer skip the native call.

frontend/src/services/GeofencingService.ts at 26b85e6:

  // Nothing to monitor and nothing previously registered → skip the native
  // round-trip (the common case for owners with no location reminders).
  if (next.length === 0 && current.length === 0) return;

Everything else re-registers unconditionally. The native call is a remove-then-add of a handful of circles, idempotent and cheap; the early return was optimising a round-trip that costs nothing, at the price of an invariant it could not observe.

That covers the app being opened. It does not cover the days when it is not, so the persisted set from the first block gained a consumer that needs no JavaScript at all.

frontend/android/app/src/main/AndroidManifest.xml at 7a0a6ba:

      <receiver
        android:name=".GeofenceBootReceiver"
        android:exported="false">
        <intent-filter>
            <action android:name="android.intent.action.BOOT_COMPLETED" />
            <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
        </intent-filter>
      </receiver>

The receiver reads the JSON back from SharedPreferences and calls the same register function. Later, a WorkManager periodic job on a six-hour interval, enqueued with ExistingPeriodicWorkPolicy.KEEP, started doing the same, because Play services also drops regions when location becomes unavailable (airplane mode, location toggled off) and never restores them. A coarse periodic re-arm is the battery-acceptable version of the polling we refused to do: it re-registers a set, it does not read a position.

The third silence: an anchor that was not where the house was

One more class of "never fired", smaller and instructive. "Home" cannot be geocoded; the user dictates an address, and the geocoder, lacking the house number, returns the centroid of the street. On a long street the front door can sit two hundred metres from that point, outside the tight circle an at-the-place reminder gets by default. The geofence was armed, permitted, and centred on the wrong spot.

backend/src/orchestrator/setLocationReminder.ts at 49a00fb:

export function radiusForReminder(
  content: string,
  placeQuery: string,
  explicitRadius?: number
): number {
  let radius =
    typeof explicitRadius === 'number' && explicitRadius >= 100
      ? Math.round(explicitRadius)
      : defaultRadiusForIntent(content);
  if (isColloquialPlace(placeQuery)) {
    radius = Math.max(radius, HOME_MIN_RADIUS_M);
  }
  return radius;
}

HOME_MIN_RADIUS_M is 400. A colloquial place ("home", "the office") gets a floor wide enough to swallow street-level imprecision; named places keep their intent-derived radius, and an explicit distance from the user wins. No app rebuild was needed: the native side reads radius_m from the projection, and the unconditional re-register picked the new value up on the next sync.

What the code does not prove

Battery is asserted by architecture, not measured. The claim is "no location loop, OS geofences, one periodic re-arm every six hours"; nobody has profiled the app against a device with and without active reminders.

The unit tests cover the pure functions: shouldFire (direction, day-of-week window, cooldown), diffGeofences, the haversine distanceMeters, and insideOneShotEnters, the catch-up projection that fires a pending one-shot when the app opens already inside its circle, because setInitialTrigger(0) means a region re-armed after you arrived will never report the arrival. Nothing tests the Kotlin module. The Handler.post between the two permission steps is justified by a comment about listener lifetime, not by a test that would fail without it. The original bug, a promise resolved without awaiting, is exactly what a JS-side test cannot see: the mock resolves whatever you told it to.

The offline path duplicates logic. When the receiver wakes with no React context, it re-implements the temporal window and cooldown checks in Kotlin, mirroring shouldFire. Two implementations of one rule, kept in step by discipline. That notification also carries a hard-coded title in one language, because the path has no access to the JS translation layer.

And the diagnosis of the second bug rested on the location service's dump, read over adb on one device. The fix follows from a documented property of the platform, but the timeline that convinced us came from one phone's logs.

The lesson I kept: a client-side cache of "what I told the OS" records intent, not state. Reboots, updates and service-side purges reset state without touching intent, and an early return keyed on intent alone will sooner or later decline to repair a state it never looked at. If the repair is idempotent and cheap, do not guard it.

The geofences described here ship in the Android app at xneuronal.com.

A read-only offline mirror in op-sqlite: network first, upsert-MERGE, never delete-then-insert

XNeuronal — Mon, 31 Aug 2026 08:59:18 +0000

Our app had no offline mode for its first two months: every screen was a REST call, and with the radios off every screen was empty. The fix that shipped is deliberately small. The server stays the only source of truth, and the phone keeps a read-only mirror of what it last saw, filled as a side effect of every successful fetch and read only when a fetch fails. No sync engine, no delta endpoint, no conflict resolution.

That design took one evening to write and eight minutes to break. This is why its convergence rule became "replace by scope, but merge the survivors", and how a later bug turned a read into a wipe. React Native 0.81, @op-engineering/op-sqlite. Every block below is copied from the repository at the commit named above it; 9bed3a1 is the current head.

One table, one opaque column

The cache does not model the domain. neurons_cache has an id primary key, four indexed text columns (status, sphere, type, due_at) and a payload column holding the JSON the server returned. No migration when the API grows a field; SQLite only discriminates on the four columns. A deliberately dumb store.

Network first, write through, fall back

Every read service follows the same shape. Try the network. On success, hand the rows to the cache without awaiting it and return them. On failure, probe the socket so the offline banner shows up fast, then serve the mirror if it has ever been primed.

frontend/src/services/MemoryService.ts at 9bed3a1, inside listNeurons:

    // Write-through : an unfiltered "active" fetch is a full snapshot of the
    // active set → replace-by-scope (deletions converge) ; anything narrower
    // only upserts.
    const isFullActiveList =
      filters.status === 'active' && !filters.sphere && !filters.type && !filters.limit;
    void (isFullActiveList
      ? neuronCache.replaceActiveSet(rows as unknown as Array<Record<string, unknown>>)
      : neuronCache.upsertMany(rows as unknown as Array<Record<string, unknown>>)
    ).catch(() => {});

And the start of the catch (err) branch of the same function:

    webSocketService.ensureAlive();
    // Offline fallback : serve the mirror if it has ever been primed.
    try {
      if (await neuronCache.isPrimed()) {
        const cached = await neuronCache.list({
          status: filters.status,
          sphere: filters.sphere,
          type: filters.type
        });
        return cached as unknown as MemoryNeuron[];
      }

The lines that follow swallow any cache failure and rethrow the original network error. Two decisions hide here. The primed flag separates "offline with a genuinely empty memory" from "never synced": only the second should surface an error, and an empty table cannot tell you which one you are in. And the void ...catch(() => {}) means a cache failure can never fail a read; the cache is a side effect, not a dependency.

Replace by scope: convergence without tombstones

The server can delete rows or move them out of a status, and a cache that only ever upserts keeps ghosts forever. Instead of tombstones or a delta endpoint, a fetch that is a complete snapshot of some scope replaces that scope: the unfiltered active list replaces the active set, a calendar window replaces that window. Anything narrower only upserts, because it cannot know what it did not receive.

frontend/src/services/NeuronCacheDb.ts at d31f159, the commit that introduced the mirror:

  /** Full sync of a calendar window [fromIso, toIso]. */
  async replaceWindow(
    fromIso: string,
    toIso: string,
    rows: Array<Record<string, unknown>>
  ): Promise<void> {
    const db = await dbForCurrentOwner();
    await db.execute(
      'delete from neurons_cache where due_at is not null and due_at >= ? and due_at <= ?',
      [fromIso, toIso]
    );
    await upsertInto(db, rows);
    await setMeta(db, 'primed', '1');
  },

Correct if one endpoint feeds the table. Two do.

Two REST shapes, one row

The list endpoint returns each neuron with graph fields, mention_count and last_mentioned_at among them, which size the nodes of the home constellation. The calendar endpoint returns the same neuron with agenda fields and without the graph fields. Same primary key, two projections.

The cache was designed for this: its upsert reads the existing payload, spreads the incoming row over it, and writes the union back.

frontend/src/services/neuronCacheGuards.ts at 9bed3a1:

export function mergePayload(
  existingJson: string | null,
  incoming: Record<string, unknown>
): string {
  const existing = existingJson ? parsePayload(existingJson) : null;
  return JSON.stringify(existing ? { ...existing, ...incoming } : incoming);
}

frontend/src/services/NeuronCacheDb.ts at 9bed3a1:

async function upsertInto(db: DB, rows: Array<Record<string, unknown>>): Promise<void> {
  for (const row of rows) {
    const id = idOf(row);
    if (!id) continue;
    const existing = await db.execute('select payload from neurons_cache where id = ?', [id]);
    const existingPayload = existing.rows[0] ? String(existing.rows[0].payload) : null;
    const payload = mergePayload(existingPayload, row);
    const merged = parsePayload(payload) ?? row;
    await db.execute(
      `insert or replace into neurons_cache (id, status, sphere, type, due_at, payload)
       values (?, ?, ?, ?, ?, ?)`,
      [
        id,
        typeof merged.status === 'string' ? merged.status : null,
        typeof merged.sphere === 'string' ? merged.sphere : null,
        typeof merged.type === 'string' ? merged.type : null,
        typeof merged.due_at === 'string' ? merged.due_at : null,
        payload
      ]
    );
  }
}

The merge is not done by SQLite. insert or replace is delete-and-insert under a friendlier name; the union exists only because the function reads the old payload first. So the invariant "a row is the union of every shape that ever fed it" is upheld by upsertInto and nothing else, and replaceWindow broke it from the outside: the delete ran before upsertInto could read, and every dated neuron in the window came back with agenda fields only.

Nothing noticed online, because the next full list refetch restored the graph fields. Offline, the constellation read the mirror, computed Math.log(1 + mention_count) on undefined, got NaN, and put it in an SVG path. On Android a NaN coordinate in a path is a native crash, not a JavaScript exception. The app died on relaunch with the radios off, the one scenario the feature existed for.

Merge the survivors, delete only the missing

The fix, eight minutes after the mirror landed, reverses the order and narrows the delete.

frontend/src/services/NeuronCacheDb.ts at 9bed3a1, unchanged since 8c4e6dc:

  async replaceWindow(
    fromIso: string,
    toIso: string,
    rows: Array<Record<string, unknown>>
  ): Promise<void> {
    const db = await dbForCurrentOwner();
    await upsertInto(db, rows);
    const existing = await db.execute(
      'select id from neurons_cache where due_at is not null and due_at >= ? and due_at <= ?',
      [fromIso, toIso]
    );
    const existingIds = existing.rows.map((r) => String(r.id));
    for (const id of staleWindowIds(existingIds, rows as Array<{ id?: unknown }>)) {
      await db.execute('delete from neurons_cache where id = ?', [id]);
    }
    await setMeta(db, 'primed', '1');
  },

Upsert first, so every survivor is merged. Then take the set difference between what the window holds and what the server just returned, and delete only that. staleWindowIds is a pure function with its own tests. Same scope semantics, but survivors keep the fields the other endpoint gave them.

The same commit added withGraphDefaults at read time, filling the two graph fields with safe values on any row that lacks them. That layer heals phones that already had a poisoned cache on disk, which the root fix cannot repair.

The read that wiped the cache

The mirror belongs to exactly one identity, user:<id> or device:<uuid>. Every operation first resolves the current owner and, if it differs from the stored one, wipes the database, so no row is ever shown across identities. That rule is right. Where the identity came from was not.

frontend/src/services/NeuronCacheDb.ts at 9bed3a1:

async function dbForCurrentOwner(): Promise<DB> {
  const db = await openDb();
  const owner = ownerKeyOf(await getKnownUserId(), await getDeviceId());
  const stored = await getMeta(db, 'owner');
  if (stored !== owner) {
    await wipe(db);
    await setMeta(db, 'owner', owner);
  }
  return db;
}

For a month, the owner in that function came from getSession(). The Supabase auth client refreshes the access token when you read the session past its lifetime, and if that refresh fails with a network error it returns a null session while leaving the real one on disk. So one hour after the last online use, the cache asked who owned it, was told "nobody", concluded the owner had changed from user: to device:, and deleted every row and the primed flag before serving. Coming back online flipped the key a second time, wiped again, refetched everything, and hid the whole sequence.

It had been there since the mirror's first commit, needed an expired token no test session ever reached, and was triggered by a read: opening the app offline destroyed the data it was opening to show.

The replacement reads the session blob the auth client persisted in AsyncStorage and never touches the network. It is fail-closed: an absent blob means anonymous, and a home-grown "last known user" key is dropped too, because a key outliving a sign-out would keep the previous owner's rows readable.

Cache-first paint, network overwrite

The constellation is the one screen that reads the cache before trying the network, because a blank first screen for two seconds reads as data loss.

frontend/src/hooks/useNeuronGraph.ts at 9bed3a1:

  useEffect(() => {
    let cancelled = false;
    void (async () => {
      try {
        const [cachedNodes, cachedEdges] = await Promise.all([
          neuronCache.list({ status: 'active' }),
          neuronCache.listEdges()
        ]);
        if (cancelled || cachedNodes.length === 0) return;
        setNodes((prev) => (prev.length > 0 ? prev : (cachedNodes as unknown as MemoryNeuron[])));
        setEdges((prev) => (prev.length > 0 ? prev : (cachedEdges as unknown as MemoryEdge[])));
        setReady(true);

The effect ends with an empty catch and a cleanup setting cancelled. The functional updater is the interesting line. Two reads race, SQLite and the network. If the network wins, prev.length > 0 is already true and the stale cache result is discarded. If the cache wins, it paints, and the network result replaces it through the unconditional setNodes(rows) in refresh. "Non-empty already" is the whole arbitration.

What the code does not prove

replaceActiveSet still does delete-then-insert on status = 'active'. The code supports one reason it has not bitten: the list row is the richer shape, so overwriting an agenda row with it loses nothing the constellation needs. But the invariant is now asymmetric, protected on one path by ordering and on the other by an accident of which endpoint is fatter. The day the calendar endpoint grows a field the list endpoint lacks, that path strips it. Nobody has written that test.

mergePayload is a shallow spread: a nested metadata object from the incoming row replaces the stored one wholesale. upsertInto runs a select and an insert per row, sequentially, with no transaction; nothing measures where that hurts.

The tests for the owner bug drive the real data path: a session blob in AsyncStorage as the auth client writes it, a getSession mock returning null on top, and an assertion that no delete from neurons_cache is ever executed. The tests for the merge bug cover staleWindowIds and withGraphDefaults in isolation. Nothing exercises replaceWindow against a real SQLite with two shapes of the same id. The invariant that crashed the app is documented in three comments and enforced by the order of two lines.

The lesson I kept is that "replace by scope" is a statement about ids, not about rows. The scope says which ids should exist afterwards, nothing about what each row should contain when more than one endpoint contributes to it. Once two projections of the same entity share a primary key, delete-then-insert stops being a cache refresh and becomes a lossy projection, and the loss shows up wherever the cache is read without the network to hide it.

The mirror described here ships in the Android app at xneuronal.com.

The editor that swallowed the last sentence: a React Native TextInput unmounted before onBlur, fixed in three layers

XNeuronal — Mon, 31 Aug 2026 08:26:45 +0000

An inline editor has one job: what you type is what gets saved. Ours lost the last field you touched, only when you tapped the Done button without leaving the field first, and it did so without a warning, a red box, or a failed request. The keystrokes were on screen one moment and gone the next, and the server had never heard of them.

This is a React Native 0.81 project on the New Architecture. The editor lives inside a structured card (a title, a row of chips, sections of checkable items, numbered steps). Every piece of text on the card is a tap-to-edit field: tap a word, it becomes a TextInput, blur it, the new value is sent as a PATCH. The bug took two commits and three distinct mechanisms to close, and the interesting part is why the first correct fix was not enough. Every block below is copied from the repository at the commit named above it.

The contract that looked fine

The field component renders one of three things depending on two booleans: editable (the parent's edit mode) and focused (its own state). Not editable means plain Text. Editable and idle means a Pressable that turns focus on. Editable and focused means the TextInput, and the save happens on blur through a five line commit function that clears focused and calls onSave(draft) when the draft differs from value.

frontend/src/components/memocard/EditableText.tsx at commit a3a01e5, the day the editor landed. The first lines are the tail of the if (!editable) branch, the rest is the focused branch:

  if (!value) return <View style={containerStyle} />;
  return (
    <View style={containerStyle}>
      <Text style={[textStyle, italic && styles.italic, textAlign ? { textAlign } : null]}>
        {value}
      </Text>
    </View>
  );
}

if (focused) {
  return (
    <View style={[containerStyle, styles.focusedWrap]}>
      <TextInput
        ref={inputRef}
        value={draft}
        onChangeText={setDraft}
        onBlur={commit}
        onSubmitEditing={multiline ? undefined : commit}
        autoFocus
        multiline={multiline}
        maxLength={maxLength}
        placeholder={placeholder}
        placeholderTextColor={colors.textSecondary}
        blurOnSubmit={!multiline}
        returnKeyType={multiline ? 'default' : 'done'}
        style={[
          textStyle,
          italic && styles.italic,
          textAlign ? { textAlign } : null,
          styles.input
        ]}
      />
    </View>
  );
}

Read the order of the branches. !editable wins over focused. So when the parent flips edit mode off while this field still holds focus, the very next render skips the TextInput branch entirely and returns a Text. The input is unmounted in that commit. Its onBlur is a closure that belongs to a fiber that no longer exists; whether the native side ever dispatches a blur for a view it is busy detaching does not matter, because nobody is listening. The typed characters live in draft, a piece of React state, and the state dies with the component.

That is the whole bug. No error, because nothing failed. The PATCH was never built.

Layers one and two: watch the prop, drop the keyboard

The first fix, thirty three minutes later, added two independent guards.

The obvious one is in the button. Before this commit, the Done handler was a single setIsEditing(false).

frontend/src/components/overlays/NoteOverlay.tsx at commit ed5a883:

{isEditing ? (
  <Pressable
    onPress={() => {
      // Drop the keyboard first so the currently-focused
      // TextInput blurs and commits its draft before we
      // unmount it via the editable-toggle.
      Keyboard.dismiss();
      setIsEditing(false);
    }}
    style={styles.doneButton}
    accessibilityRole="button"
    accessibilityLabel="Terminer l'édition"
  >
    <Text style={styles.doneText}>Terminé</Text>
  </Pressable>
) : (
  <View />
)}

Keyboard.dismiss() blurs the currently focused input. But the blur event travels from native to JavaScript asynchronously, while setIsEditing(false) is queued in the same handler. Nothing guarantees that the blur is processed before the render that removes the input commits. This layer wins the race often enough to look like a fix, which is exactly why it cannot be the only one.

The second guard is in the field itself. It mirrors its state into refs, then watches editable.

frontend/src/components/memocard/EditableText.tsx at commit ed5a883:

const [focused, setFocused] = useState(false);
const [draft, setDraft] = useState(value);
const inputRef = useRef<TextInput>(null);
// Mirror draft & value in refs so the editable-toggle effect below can
// read the latest values without re-running every keystroke.
const draftRef = useRef(draft);
const valueRef = useRef(value);
const onSaveRef = useRef(onSave);
useEffect(() => {
  draftRef.current = draft;
}, [draft]);
useEffect(() => {
  valueRef.current = value;
  onSaveRef.current = onSave;
}, [value, onSave]);

useEffect(() => {
  if (!editable && focused) {
    const draftNow = draftRef.current;
    if (draftNow !== valueRef.current) onSaveRef.current(draftNow);
    setFocused(false);
  }
}, [editable, focused]);

This effect runs after the commit that already removed the TextInput, and that is fine: the draft was never in the native view, it was in React state, and the component that owns that state is still mounted. The refs keep the dependency list down to [editable, focused] so the effect does not re-run on every keystroke, and they make sure the callback invoked is the latest onSave, not the one captured when the effect was created. The draftNow !== valueRef.current guard means that if the native blur does arrive as well, the worst case is a second PATCH with an identical body, not a wrong one.

This layer is correct. It covers the title, the chips, the section headings, whose wrappers stay the same element in both modes. It did nothing for the steps.

Why the correct fix arrived too late

The step rows are tappable in read mode, so you can tick a step off while cooking. In edit mode they are not, so the row is a plain container with a delete badge. The component picked the wrapper element by mode.

frontend/src/components/memocard/MemoFiche.tsx at commit b7f346e, the edit branch of the step row:

if (editing) {
  return (
    <View key={idx} style={[styles.stepRow, last && styles.stepRowLast]}>

And the read branch, a few lines below:

return (
  <Pressable
    key={idx}
    onPress={() => onToggle(idx)}
    accessibilityRole="checkbox"
    accessibilityState={{ checked }}
    style={({ pressed }) => [
      styles.stepRow,
      last && styles.stepRowLast,
      pressed && styles.stepRowPressed
    ]}
  >

Same key, different element type. React's reconciler compares the type before anything else, and when it differs it does not update the subtree, it throws it away and builds a new one. So when Done flips editing, the EditableText inside a step row is not re-rendered with editable={false}. It is unmounted. An effect keyed on [editable, focused] needs a render to observe the prop change, and that render never happens. Layer one was right about the mechanism and simply never got to run.

Layer three: flush on unmount

The second commit, twenty five minutes after the first, added the guard that survives a teardown: a cleanup function on an effect with an empty dependency list, which React calls exactly once, when the component unmounts. It also added a fourth mirror, focusedRef, kept in sync by the same kind of one-line effect as the other three.

frontend/src/components/memocard/EditableText.tsx at commit b7f346e:

useEffect(
  () => () => {
    if (focusedRef.current && draftRef.current !== valueRef.current) {
      onSaveRef.current(draftRef.current);
    }
  },
  []
);

Everything in that cleanup is a ref, including focused, which is why the fourth ref appeared. State captured at render time is frozen at whatever the first render saw, because the effect closure was created once. By the time the cleanup runs, the only trustworthy values are the ones written into refs by the small mirroring effects on every change.

The two field-side layers are complementary, not redundant. When the field survives the toggle and re-renders as Text, its TextInput child unmounts but the field does not, so no cleanup fires and layer one does the work. When the parent swaps element types, or deletes the whole section while you are typing in it, the field unmounts and only layer three can act. The keyboard dismiss is the belt over both braces.

The line that tells two failures apart

The same first commit touched one file outside the app: backend/src/routes/anonymous.ts gained a console.log when a PATCH arrives, with the neuron id and the list of patched fields, and a console.warn when the database rejects it. Not a fix. "My edit did not save" has two completely different causes with one face: the request never left the phone, or the database refused the row. Before those two lines, the server log could not distinguish them. The next time the symptom shows up, one read of the feed says which side of the network to look at.

What the diff does not prove

The account above is the one the code supports. A few things it does not support.

The checkable item rows in ChecklistSection.tsx have the very same View versus Pressable swap at b7f346e. So the story that layer one "worked for the items but not the steps" cannot be explained by the code; either the items were tested by blurring before tapping Done, or the keyboard race happened to win those times. Nobody bisected.

Nothing tests any of the three layers. The one test file that imports EditableText uses it as a type to locate elements, not to exercise a flush. The structural fix was in the parent: render one element type in both modes and toggle disabled, and the unmount never happens. That fix was never tried. The swap is still in MemoFiche.tsx today, which means layer three is still load-bearing, not a leftover.

Four later commits touched EditableText.tsx (translations, a tint on editable fields, a keyboard type, an auto-focus flag). None of them touched the three effects, which are in the current file character for character.

And the keyboard dismiss is still there. Whether it ever decides an outcome anymore, with the other two layers in place, is something the repository cannot say.

The lesson I kept is narrower than "use refs in cleanups". When a React Native symptom is "nothing happened", ask which node was removed and by whom before asking which callback failed. The callback was fine. The node it was attached to had already been thrown away by a parent that, from its own point of view, was only changing a wrapper.

The card this editor lives in is at xneuronal.com.

The checkbox Android refused to paint: SVG, overflow:hidden, elevation, and why we redrew it in Skia

XNeuronal — Sat, 29 Aug 2026 11:33:08 +0000

A checkbox is the least interesting component in any app, right up to the moment it stops drawing. This is the story of one that stopped drawing on Android only, on a Tuesday in May, thirty minutes after we had made it prettier. It is a small bug, but the diff trail shows something I see a lot in React Native work: the fix that ships is not the same thing as the cause that was proven, and it is worth knowing the difference.

The app is a React Native 0.81 project on the New Architecture. The component is a tickable ingredient list inside a recipe card. Everything below is copied from the repository or from the exact commits, with the file path above each block.

The checkbox that worked

Before anyone touched it, the checkbox was a plain View with a border, and a Text glyph inside when checked. Nothing to see, nothing to break.

frontend/src/components/memocard/ChecklistSection.tsx, before commit f729381:

<View style={[styles.checkbox, checked && styles.checkboxDone]}>
  {checked ? <Text style={styles.checkmark}>✓</Text> : null}
</View>

checkbox: {
  width: 22,
  height: 22,
  borderRadius: 7,
  borderColor: '#cbd5e1',
  borderWidth: 1.5,
  alignItems: 'center',
  justifyContent: 'center'
},
checkboxDone: {
  borderColor: colors.primary,
  backgroundColor: colors.primary
},

It rendered identically on iOS and Android. It was also flat blue, and the design mockup was not flat blue.

The checkbox that matched the mockup

The mockup asked for a 135 degree cyan to blue gradient fill, a soft blue halo underneath, and a white check on top. React Native views cannot paint a gradient by themselves, so the first instinct was react-native-svg, which was already a dependency for icons and the logo. Commit f729381 replaced the flat box with a wrapper View hosting an absolutely positioned Svg and the same Text glyph over it.

frontend/src/components/memocard/ChecklistSection.tsx at commit f729381:

function CheckboxBox({ checked }: { checked: boolean }): React.JSX.Element {
  if (!checked) {
    return <View style={styles.checkboxEmpty} />;
  }
  return (
    <View style={styles.checkboxFilled}>
      <Svg
        width={CHECKBOX_SIZE}
        height={CHECKBOX_SIZE}
        style={StyleSheet.absoluteFill}
      >
        <Defs>
          <LinearGradient
            id="checkboxGradient"
            x1={0}
            y1={0}
            x2={CHECKBOX_SIZE}
            y2={CHECKBOX_SIZE}
            gradientUnits="userSpaceOnUse"
          >
            <Stop offset="0" stopColor={colors.cyan} />
            <Stop offset="1" stopColor={colors.primary} />
          </LinearGradient>
        </Defs>
        <Rect
          x={0}
          y={0}
          width={CHECKBOX_SIZE}
          height={CHECKBOX_SIZE}
          rx={CHECKBOX_RADIUS}
          ry={CHECKBOX_RADIUS}
          fill="url(#checkboxGradient)"
        />
      </Svg>
      <Text style={styles.checkmark}>✓</Text>
    </View>
  );
}

And the wrapper style, which is where the trouble lives:

frontend/src/components/memocard/ChecklistSection.tsx at commit f729381:

/** Filled box hosts the SVG gradient layer + the checkmark on top. The
 *  drop shadow reads as the soft "pressed-in" cyan halo from the mockup
 *  (rgba(59,109,248,0.30) at offset 0/2 with 8 blur radius). */
checkboxFilled: {
  width: CHECKBOX_SIZE,
  height: CHECKBOX_SIZE,
  borderRadius: CHECKBOX_RADIUS,
  alignItems: 'center',
  justifyContent: 'center',
  overflow: 'hidden',
  shadowColor: colors.primary,
  shadowOffset: { width: 0, height: 2 },
  shadowOpacity: 0.30,
  shadowRadius: 8,
  elevation: 3
},

Read that style as three separate requests to the platform. borderRadius plus overflow: 'hidden' asks the wrapper to clip its children to a rounded shape. shadow* asks iOS for a blurred halo. elevation asks Android for the same halo, except that on Android a halo is not a paint effect, it is a z-axis property that the compositor uses to compute an outline and draw a shadow behind it.

On iOS the result matched the mockup on the first build. On Android, a checked item showed the blue halo and a completely empty square. No gradient. No check.

What we assumed, and what the diff says

The first hypothesis was react-native-svg. The library mounts its own native view, and a native view inside a clipped, elevated parent is a well known way to get nothing drawn on Android. The commit message of the fix, d0e80fe, states it that way: SVG plus overflow: 'hidden' plus elevation is a bad combination, the inner Svg never rendered.

The diff tells a more careful story. Look at the JSX again. The wrapper had two children, the Svg and a plain Text with a Unicode check mark. The text is not SVG. It is a stock ReactTextView. And it disappeared too. Whatever swallowed the gradient also swallowed a native text node, which means the SVG library was, at best, a co-suspect. The common parent of both victims is the wrapper style: a rounded View that clips its children and carries an elevation.

This matters because it changes where the fix has to go. If the SVG were the problem, swapping the renderer would be enough. If the wrapper is the problem, swapping the renderer changes nothing and removing overflow: 'hidden' is the actual fix. The commit did both at once.

The Skia rewrite

The project already shipped @shopify/react-native-skia for the animated orb on the home screen, so a Skia canvas cost no new dependency. The rewrite paints the whole box, rounded rectangle, gradient and check stroke, into a single Canvas. One native surface, no view hierarchy to clip, no text glyph to align.

frontend/src/components/memocard/ChecklistSection.tsx, current:

function CheckboxBox({ checked }: { checked: boolean }): React.JSX.Element {
  // Built once and reused for every row : a stylised ✓ shape sized to
  // sit comfortably inside the 22 px box with a touch of padding.
  const checkPath = useMemo(() => {
    const p = Skia.Path.Make();
    p.moveTo(5.5, 11.5);
    p.lineTo(9.5, 15.5);
    p.lineTo(16.5, 7);
    return p;
  }, []);

  if (!checked) {
    return <View style={styles.checkboxEmpty} />;
  }

  return (
    <View style={styles.checkboxFilled}>
      <Canvas style={styles.checkboxCanvas}>
        <RoundedRect
          x={0}
          y={0}
          width={CHECKBOX_SIZE}
          height={CHECKBOX_SIZE}
          r={CHECKBOX_RADIUS}
        >
          <LinearGradient
            start={vec(0, 0)}
            end={vec(CHECKBOX_SIZE, CHECKBOX_SIZE)}
            colors={[colors.cyan, colors.primary]}
          />
        </RoundedRect>
        <Path
          path={checkPath}
          color="white"
          style="stroke"
          strokeWidth={2.2}
          strokeCap="round"
          strokeJoin="round"
        />
      </Canvas>
    </View>
  );
}

Two details are doing real work here. The check is a Path stroked with round caps, not a font glyph, so it looks the same on every device regardless of which font Android picks for U+2713. And the rounded rectangle is drawn by Skia, so the wrapper no longer needs to clip anything. Which brings us to the style that actually changed.

frontend/src/components/memocard/ChecklistSection.tsx, current:

checkboxFilled: {
  width: CHECKBOX_SIZE,
  height: CHECKBOX_SIZE,
  borderRadius: CHECKBOX_RADIUS,
  shadowColor: colors.primary,
  shadowOffset: { width: 0, height: 2 },
  shadowOpacity: 0.30,
  shadowRadius: 8,
  elevation: 3
},
checkboxCanvas: {
  width: CHECKBOX_SIZE,
  height: CHECKBOX_SIZE
},

overflow: 'hidden' is gone. alignItems and justifyContent are gone because the canvas fills the box exactly. The shadow stays on the outer View, which is where Android wants it: the elevated view owns a rounded outline, the compositor draws the halo from that outline, and nothing inside asks to be clipped.

The pattern generalises. On Android, keep three responsibilities on three different nodes: the node that carries elevation, the node that clips with overflow: 'hidden', and the node that paints content. Putting all three on one View is not guaranteed to fail, but when it fails it fails silently, with no warning in Logcat and no red box, and it only fails on one platform.

What it cost

Almost nothing in dependencies, since Skia was already linked. About fifty lines changed in one file. The visible cost is elsewhere: the app now carries two vector renderers. react-native-svg still draws a dozen components, icons, the logo, the memory constellation. Skia draws the orb, the speech halo, a decay ring in the messaging layer, and now this checkbox. Anyone opening the codebase has to know which one to reach for, and the honest answer is historical rather than principled.

There was one unexpected payoff. Months later we needed a different mark for lists that record what happened rather than what is left to do: a bare gradient check with no box, deliberately not looking tappable. With the path already in Skia, it was a fifteen line component that reuses the same gradient and the same footprint.

frontend/src/components/memocard/ChecklistSection.tsx, current:

function LogCheckMark(): React.JSX.Element {
  const checkPath = useMemo(() => {
    const p = Skia.Path.Make();
    p.moveTo(4.5, 12);
    p.lineTo(9, 16.5);
    p.lineTo(17.5, 6);
    return p;
  }, []);

  return (
    <Canvas style={styles.checkboxCanvas}>
      <Path
        path={checkPath}
        style="stroke"
        strokeWidth={2.6}
        strokeCap="round"
        strokeJoin="round"
      >
        <LinearGradient
          start={vec(0, 0)}
          end={vec(CHECKBOX_SIZE, CHECKBOX_SIZE)}
          colors={[colors.cyan, colors.primary]}
        />
      </Path>
    </Canvas>
  );
}

A gradient stroke in react-native-svg is possible, but it means another Defs, another string id, and another url(#...) reference that has to be unique across every instance on screen. In Skia the gradient is a child of the shape. That is the kind of ergonomic difference that quietly decides which renderer a team ends up preferring.

What we would do differently

We never bisected. The fix removed overflow: 'hidden' and replaced the SVG in the same commit, so to this day the repository cannot say whether react-native-svg was guilty or merely present. The right sequence would have taken ten minutes: keep the SVG version, delete the single overflow: 'hidden' line, rebuild on Android, look. If the gradient appears, the SVG was innocent and the Skia rewrite is a taste decision rather than a bug fix. If it does not, then the library really does mishandle that parent and the rewrite was necessary. Either answer is more useful than a commit message that names three suspects and convicts them together.

The second thing is about the timeline of that afternoon. The gradient landed at 12:31. The Android blank box was fixed at 13:05. The rest of the day went to an inline editor for the same card, and two of those later commits fixed edits that silently failed to save because a TextInput was unmounted before its onBlur could fire. Different bug, same shape: a component torn down before it finished its job, on a code path that produced no error. When a React Native symptom is "nothing happened", the first question is now always "which node got removed, and by whom", before any library gets blamed.

The checkbox is 22 pixels wide. It took two commits, one honest mistake in attribution, and a second renderer to get it to draw on both platforms. It draws now, and the list it lives in is at xneuronal.com.

We wrote a graph of edges for months and never traversed it. Here is the one-hop query, and why we stopped at one.

XNeuronal — Fri, 28 Aug 2026 10:26:05 +0000

We had a neurons_edges table. It was filling up nicely. Every time the system noticed that two memories were about the same person, or that one superseded another, it wrote a row.

Retrieval never read a single one of them.

Not because of a bug. Because nobody had wired the read path. The edges were an audit trail that looked like a graph, and the whole retrieval stack ran on vector similarity alone. The system was recording its own associations and then answering questions without opening them.

This post is the read path we added, why it stops at one hop, and the two failure modes that decision avoids.

The flaw with no symptom

This is the part worth dwelling on, because it is the reason it survived for months.

A missing traversal produces no error. No exception, no timeout, no empty result. The query returns rows, they are plausible, and they are simply poorer than they should have been. There is no signal anywhere that a better answer existed.

The only way we found it was by asking a question we knew the answer to, and noticing that one obvious memory did not come back.

Why cosine similarity misses linked rows

Every memory carries an embedding, and retrieval ranks by cosine distance. That works well, and it fails on exactly one shape: two rows that are explicitly related but share almost no vocabulary.

row A: "renew the prescription before the end of the month"
row B: "Dr Guy, Thursday 2pm, blood test in three months"

Semantically adjacent to a human. Lexically almost disjoint. Their embeddings sit far enough apart that a top-k query on "prescription" will not surface B.

An edge between them says, flatly, that they belong together. That edge existed. It was in the table. Nothing read it.

The table

create table xneuronal.neurons_edges (
  id            uuid primary key default gen_random_uuid(),
  user_id       uuid,
  device_id     text,
  from_node_id  uuid not null,
  to_node_id    uuid not null,
  relation_type text not null,
  weight        double precision not null default 1.0,
  valid_from    timestamptz,
  valid_to      timestamptz,
  created_at    timestamptz not null default now()
);

Two things to note.

user_id and device_id both nullable, exactly one of them set. That is the anonymous-mode pattern: a device can own rows before anyone signs up, and every query scopes on whichever identity is present. It costs a branch in every single query, and it is the price of not forcing an account on first launch.

valid_from / valid_to because an edge can stop being true. A relation is not deleted when it expires, it is closed. Same principle as everywhere else in this schema: nothing is erased, things change state.

The traversal

The read path is deliberately dumb. Two round-trips, no recursion, no CTE.

async expandByEdges(
  auth: AuthContext,
  seedIds: string[],
  relationTypes: NeuronRelationType[] = ['relates_to', 'concerns']
): Promise<Neuron[]> {
  if (seedIds.length === 0) return [];
  const { column, value } = authScope(auth);

  const { data: edges } = await serviceClient
    .from('neurons_edges')
    .select('from_node_id, to_node_id, relation_type')
    .eq(column, value)
    .in('relation_type', relationTypes)
    .or(`from_node_id.in.(${seedIds.join(',')}),to_node_id.in.(${seedIds.join(',')})`);

  if (!edges?.length) return [];

  const seedSet = new Set(seedIds);
  const neighbourIds = new Set<string>();
  for (const e of edges) {
    if (!seedSet.has(e.from_node_id)) neighbourIds.add(e.from_node_id);
    if (!seedSet.has(e.to_node_id)) neighbourIds.add(e.to_node_id);
  }
  if (neighbourIds.size === 0) return [];

  const { data: neighbours } = await serviceClient
    .from('neurons')
    .select('*')
    .eq(column, value)
    .in('id', [...neighbourIds]);

  return neighbours ?? [];
}

In plain SQL that is:

select n.*
from xneuronal.neurons n
where n.user_id = $1
  and n.id in (
    select case when e.from_node_id = any($2) then e.to_node_id
                else e.from_node_id end
    from xneuronal.neurons_edges e
    where e.user_id = $1
      and e.relation_type = any($3)
      and (e.from_node_id = any($2) or e.to_node_id = any($2))
  )
  and n.id <> all($2);

The edges are undirected for this purpose: we do not care which end the seed was on, we want the other one. Hence the case and the two-sided predicate.

Caller side, the traversal is opt-in per query, and the seeds are whatever the vector search already returned. The result sets are merged and deduplicated.

The call site asks for three relation types rather than the default two:

neuronService.expandByEdges(auth, seedIds, ['relates_to', 'concerns', 'same_person'])

same_person is the one that earns its place. Querying a single dated observation about someone reconstructs that person's whole timeline in one call, instead of the model issuing a chain of follow-up queries and stitching them together itself.

Why one hop

The technical reason is the boring one: past one hop you need cycle detection and a depth limit, and you are writing a recursive CTE for a feature nobody asked for yet.

The real reason is about result quality, and it took a moment to accept.

At two hops, in a graph of any density, you pull back nearly everything. Take an average degree of 4. One hop from 10 seeds gives you roughly 40 candidates. Two hops gives you 160, minus overlap, on a store where a heavy user has a few thousand rows. You have not enriched the answer, you have replaced it with a dump.

A memory that returns everything remembers nothing. The immediate neighbourhood is almost always relevant. The neighbourhood of the neighbourhood almost never is, because by then the only thing connecting a row to your question is that both of them touch something you once mentioned.

The failure is caught, not hidden

The call site degrades to the base result if the traversal blows up:

const neighbours = await neuronService
  .expandByEdges(auth, seedIds, ['relates_to', 'concerns', 'same_person'])
  .catch((err) => {
    console.warn('[query_neurons] expand failed:', err instanceof Error ? err.message : err);
    return [] as Neuron[];
  });

The distinction that matters is the console.warn. A catch that returns a default and says nothing is how you end up with a feature that has been dead for three weeks while every dashboard stays green. The warn line is what makes the difference between degrading and disappearing.

Degrading is right here for one narrow reason: the traversal is strictly additive. If it throws, the user gets the answer they would have gotten last week. If it were allowed to propagate, one bad edge row would take down retrieval entirely, and retrieval is the product.

The rule I would generalise: catch and continue only when the code path could be deleted without changing correctness, and always log when you do. If removing it turns a right answer into a wrong one, it has to throw.

The indexes that carry it

create index neurons_edges_from_idx on xneuronal.neurons_edges (from_node_id);
create index neurons_edges_to_idx   on xneuronal.neurons_edges (to_node_id);

create index neurons_edges_user_type_idx
  on xneuronal.neurons_edges (user_id, relation_type)
  where user_id is not null;

create index neurons_edges_device_type_idx
  on xneuronal.neurons_edges (device_id, relation_type)
  where device_id is not null;

Two single-column indexes because the predicate hits both ends independently, and two partial composite indexes on the scoping column plus relation type. Partial, because a row has either a user_id or a device_id, never both, so a full index would be half dead weight on each.

What it changed

The question that motivated all of this is "what do you know about X". Before, that meant a broad vector query and hoping similarity did the sorting. Now it is a lookup on the subject, then one hop out.

Cost: one extra round-trip on queries that opt in.

The wider lesson is the one about the flaw with no symptom. We had the data, we had the write path, we had months of edges accumulating, and the read path had simply never been connected. Nothing in the monitoring could ever have told us. The only detector for that class of defect is asking a question you already know the answer to, and being honest about the answer you get back.

I build XNeuronal, an Android memory assistant. The Postgres schema behind it was covered in an earlier post about putting reminders, contacts and recipes in one table.

I put reminders, contacts and recipes in the same Postgres table. Here is the SQL, and what it cost.

XNeuronal — Tue, 25 Aug 2026 07:07:20 +0000

Every database course tells you to give each kind of thing its own table. Customers here, orders there, products over here. I did the opposite, on purpose, and four months later I still would.

Here is the schema, the query that justifies it, and the bill.

The problem: you do not know what a memory is when it arrives

I am building an assistant whose whole job is remembering. Someone says a sentence, it keeps what matters and can find it again later.

Take a perfectly ordinary sentence:

"Saw Dr Guy on Thursday, need another blood test in three months."

What is it?

A reminder, because there is a deadline.
A contact, because there is a doctor's name.
A fact, because the appointment happened.
A task, because someone has to book the next one.

All four. And which one matters depends on the next sentence, not this one.

With one table per kind, you must decide at write time. Decide early and you are wrong often: half of what people tell a memory fits no box cleanly, and the other half fits several.

There is a worse consequence. Splitting into tables splits your search. Looking for "doctor" becomes four queries against four tables, then you merge and rank the results yourself. A memory never searches inside a category. It searches everything.

The schema

One table. One row per memory. A type column tells them apart.

create table xneuronal.neurons (
  id          uuid primary key default gen_random_uuid(),
  user_id     uuid references auth.users(id) on delete cascade,
  device_id   text,
  type        text not null check (type in (
                'reminder_short', 'reminder_long', 'task',
                'memo', 'fact', 'contact'
              )),
  content     text not null,
  metadata    jsonb not null default '{}',
  embedding   extensions.vector(1536),
  due_at      timestamptz,
  status      text not null default 'active'
              check (status in ('active', 'done', 'archived')),
  created_at  timestamptz not null default now(),
  updated_at  timestamptz not null default now(),

  constraint neurons_owner_present
    check (user_id is not null or device_id is not null)
);

Deliberately poor. content is the memory in the speaker's own words, never rewritten. metadata is a bag whose shape depends on type: checklist items with their checked state, a phone number, an address, the sources of a web search.

Note neurons_owner_present. A row belongs to an account or to a device, never to neither. That single constraint is what makes anonymous use real rather than a demo mode: memories created before signing up are stored in the same table, with the same columns and the same search. Signing up does not import anything, it swaps a device id for a user id on rows that already exist.

The column that pays for everything

embedding is why the whole bet works.

It holds 1536 floats produced by an embedding model. Individually meaningless; together they place the text in a space where distance means difference in meaning. "The doctor" lands near "Dr Guy" without sharing a single character.

Now the important part: the embedding is computed for every row, whatever its type. So semantic search crosses categories for free:

select id, type, content, 1 - (embedding <=> $1) as score
from xneuronal.neurons
where status = 'active'
  and user_id = $2
order by embedding <=> $1
limit 10;

One query. One index. It returns a reminder, a contact and a recipe, ranked by relevance, and nothing in the code had to decide where to look.

With four tables you need four vector indexes, four queries, and a hand-written merge over scores that are not comparable across tables. That is not just more code. It ranks worse.

The indexes tell you the real access pattern

Four indexes, and three of them are partial:

create index neurons_user_active_idx
  on xneuronal.neurons (user_id, status, type)
  where user_id is not null and status = 'active';

create index neurons_device_active_idx
  on xneuronal.neurons (device_id, status, type)
  where device_id is not null and status = 'active';

create index neurons_due_at_idx
  on xneuronal.neurons (due_at)
  where due_at is not null and status = 'active';

create index neurons_embedding_idx
  on xneuronal.neurons
  using ivfflat (embedding extensions.vector_cosine_ops)
  with (lists = 100);

A partial index is a confession about usage: it says most queries only ever touch that slice. Done and archived rows still exist and are still findable, just slower, and that is the correct trade.

The fourth one is different in kind. ivfflat clusters vectors into 100 lists, finds the nearest lists, and only compares inside them. It is an index that agrees to be slightly wrong in exchange for being roughly a hundred times faster. For exact lookups that would be unacceptable. For similarity, where "right answer" is already a matter of degree, the loss is not perceptible.

One caveat worth knowing: ivfflat needs rows to exist before it can build meaningful clusters. Creating it on an empty table and never reindexing gives you a bad index that silently degrades recall.

What it costs

Be honest about the bill.

The database stops guarding meaning. A contact and a reminder have identical columns, so Postgres cannot require a phone number on contacts or a due_at on reminders. Those rules now live in application code, which means they hold exactly as long as your code is correct. That is a real loss, and the usual reason to keep one table per kind.

metadata is where the debt accrues. Anything fits, so anything goes in. Six months later the same fact exists in three shapes depending on which code path wrote it. Ask me how I know.

The only discipline left is that check on type. It is not much. It is also the thing that stops the whole table dissolving into a soup.

The honest framing: I traded per-kind rigour for whole-set search. For a memory, search is the product. For an invoicing system the answer would flip, and it would be just as correct.

A thirty-eight minute detour: get out of `public`

Thirty-eight minutes after creating the table I moved it, unchanged, into a schema named after the product.

If you run Postgres behind PostgREST, anything in public is exposed automatically. Row-level security still filters who reads what, and you absolutely still need it, but the table's existence is discoverable at a predictable URL. In the default configuration, creating a table publishes its name.

That is not a vulnerability, it is a design choice that helps most of the time. The problem is the direction of the default: doing nothing exposes you, and you have to act to be private.

create schema xneuronal;
alter table public.neurons set schema xneuronal;

Then expose xneuronal explicitly and leave public empty. A table someone forgets in a corner is now invisible from outside. On the client side you pay for it by naming the schema on every call:

supabase.schema('xneuronal').from('neurons')

And to be clear, because the confusion is common: a private schema is not a substitute for row-level security. It is not a lock, it is not writing the address on the door. You want both.

Four months on

The table grew. It gained columns I did not foresee, neighbours, rules. Nothing that was added has challenged the noon decision.

type accepts more than six values now. metadata became a genuine subject with its own rules and accidents. What has not moved: one row per memory, one table for all of it, and a search that crosses categories because it never had to care about them.

If you are designing something similar: the question is not "one table or many". It is whether your product's core operation is per-kind or across-kinds. Answer that first, and the schema follows.

I write about how this assistant gets built, mistakes included, at xneuronal.com.

DEV Community: XNeuronal

The briefing said nothing today, the reminder said today: an all-day event is a date, not an instant

Two columns for one appointment

Three writers, three instants

The readers had already agreed

One convention, in one function

The fix that rang at two in the morning

Repairing the rows without shipping an app

What the code does not prove

The app that spoke German but titled everything in French: the language of a system prompt is a parameter, not a constant

Where the French came from

The fix, part one: the language becomes an argument

The fix, part two: a broken contract gets fixed on every path

Testing a prompt without calling a model

Repairing what was already written

What I would do differently

Making a killed app speak: high-priority FCM, headless JS, and the service that buys a voice its right to talk

One message, three deliveries

The headless entry point

Five gates before a word comes out

The voice is a server round-trip

The phone that was busy

The right to speak at all

What the code does not prove

An offline edit queue that can undo itself: rollback payloads, a lock, and the rule we had to delete

An entry that remembers what it replaced

Send first, queue on transport failure

The rule that had to go

Replay: order, refusal, rollback

The second trigger, without the app

What the code does not prove

Android geofences that never fired: a permission promise that lied, and a cache that outlived the OS

The shape of the thing

Root cause one: the permission promise resolved before the user answered

Root cause two: the app's cache survived what the OS forgot

The third silence: an anchor that was not where the house was

What the code does not prove

A read-only offline mirror in op-sqlite: network first, upsert-MERGE, never delete-then-insert

One table, one opaque column

Network first, write through, fall back

Replace by scope: convergence without tombstones

Two REST shapes, one row

Merge the survivors, delete only the missing

The read that wiped the cache

Cache-first paint, network overwrite

What the code does not prove

The editor that swallowed the last sentence: a React Native TextInput unmounted before onBlur, fixed in three layers

The contract that looked fine

Layers one and two: watch the prop, drop the keyboard

Why the correct fix arrived too late

Layer three: flush on unmount

The line that tells two failures apart

What the diff does not prove

The checkbox Android refused to paint: SVG, overflow:hidden, elevation, and why we redrew it in Skia

The checkbox that worked

The checkbox that matched the mockup

What we assumed, and what the diff says

The Skia rewrite

What it cost

What we would do differently

We wrote a graph of edges for months and never traversed it. Here is the one-hop query, and why we stopped at one.

The flaw with no symptom

Why cosine similarity misses linked rows

The table

The traversal

Why one hop

The failure is caught, not hidden

The indexes that carry it

What it changed

I put reminders, contacts and recipes in the same Postgres table. Here is the SQL, and what it cost.

The problem: you do not know what a memory is when it arrives

The schema

The column that pays for everything

The indexes tell you the real access pattern

What it costs

A thirty-eight minute detour: get out of public

Four months on

A thirty-eight minute detour: get out of `public`