Blank is not zero

A water test is a handful of numbers typed standing at a tank, often with wet hands, and nobody tests everything every time. So the first real decision was what an empty field means. The answer is nothing. There is no nullable value column: a parameter you didn't test produces no row at all.

for (final setting in settings) {
  final text = _controllers[setting.key]?.text.trim() ?? '';
  // An untouched field produces no reading at all. Never zero.
  if (text.isEmpty) continue;

  final value = double.tryParse(text.replaceAll(',', '.'));
  if (value == null) {
    setState(() => _error = '${setting.definition.displayName}: "$text" is not a number');
    return;
  }

  entries.add(ReadingDraft(parameterKey: setting.key, value: value,
      unit: _units[setting.key] ?? ref.read(unitsProvider).unitFor(setting.definition)));
}

The previous value sits in each field as hintText, not as text, so it's a reference you can't save by accident.

This matters most for rate of change. Each saved reading is compared with the latest reading of the same parameter, which is by construction the last time that thing was actually measured. The default reef rules allow alkalinity to move 0.5 dKH a day. Store a skipped test as zero and the next honest 8.4 dKH looks like the tank jumped 8.4 dKH overnight. Two related rules: no daily rate from readings less than 12 hours apart, because over an hour the difference is mostly the test kit, and no pH drift limit for planted tanks, where CO₂ injection swings pH every day on purpose.

Charts follow from the same model. Each parameter gets its own row and scale on a shared time axis, with points spaced by date and a dot on every real measurement. A month without a nitrate test is a long straight segment between two dots, not a dip to zero. That segment is still an interpolation the eye can read as data; making the dots obvious is the best answer I have.

Absence of a measurement is not a measurement

Nulls do appear in one place: when rows are folded into per-session snapshots to work out where a new tank is in its nitrogen cycle. A snapshot holds nullable ammonia, nitrite, nitrate, pH, KH and temperature, and a null never counts as clear or present.

bool get ammoniaClear => ammonia != null && ammonia! <= Cycling.effectivelyZero;
bool get nitriteClear => nitrite != null && nitrite! <= Cycling.effectivelyZero;
bool get nitratePresent => nitrate != null && nitrate! > 0;

bool get passesCompletionTest => ammoniaClear && nitriteClear && nitratePresent;

// In Cycling.assess: the stage comes from the newest session that measured
// ammonia or nitrite, not simply the newest session.
final latest = sorted.lastWhere(
  (s) => s.ammonia != null || s.nitrite != null,
  orElse: () => sorted.last,
);

A tank counts as cycled after two passing sessions in a row, because one clean result can be a misread. Nitrate is required so that "nothing was ever dosed" can't pass for "the bacteria are working". "Clear" means at or below 0.25 ppm, because my research notes flag a common hobby kit as reading about that on clean water.

The lastWhere exists because of a bug I found by looking at the screen, not with a test. After logging a single alkalinity reading, the cycling banner dropped back to "Setting up": the newest snapshot had no ammonia in it, and the code took that as the cycle going backwards. Stall detection had the other half of the bug. KH and pH are often tested on a different day from ammonia, so each check now uses the latest session that measured that particular thing.

Free ammonia from pH and temperature

Kits report total ammonia. The seriously toxic part is un-ionised NH₃, and its share depends on pH and temperature, as the EPA's ammonia page explains. When the user has typed all three into the same session, the rest is arithmetic.

/// pKa = 0.09018 + 2729.92 / T(K). At 25 C this gives ~9.25.
static double pKa(double temperatureC) =>
    0.09018 + 2729.92 / (temperatureC + 273.15);

/// Fraction of total ammonia present as toxic, un-ionised NH3 (0..1).
static double freeFraction({required double ph, required double temperatureC}) =>
    1 / (1 + math.pow(10, pKa(temperatureC) - ph));

static double freeAmmoniaPpm({
  required double totalAmmoniaPpm,
  required double ph,
  required double temperatureC,
}) => totalAmmoniaPpm * freeFraction(ph: ph, temperatureC: temperatureC);

The pKa expression is the same as in the Florida Department of Environmental Protection's procedure for calculating un-ionized ammonia, which writes the constant as 0.0901821, credits Thurston et al., and gives it as valid from 0 to 50 °C and pH 6 to 10. At 25 °C it puts about 0.56% of total ammonia in the free form at pH 7 and 5.4% at pH 8, matching the table in that document. One test pins down why the feature exists: 0.5 ppm total ammonia is 0.0017 ppm free at pH 6.8 and 24 °C, and 0.054 ppm at pH 8.3 and 26 °C. Same kit reading, about 33 times apart.

The result appears only when the saved session has ammonia, pH and temperature together; it doesn't borrow last week's pH. The known limitation: the expression is for fresh water. The same document says the free fraction drops slightly as ionic strength rises and gives a separate correction for saline water, which the app doesn't apply, so in a reef tank it errs high. It calculates; it doesn't diagnose.

One stored unit per parameter

Each reading keeps the value in the parameter's canonical unit and, beside it, exactly what the user typed and in which unit, so a conversion bug can't destroy the original observation. Nitrate is stored as the NO₃ ion, alkalinity in meq/L, salinity in ppt, temperature in °C. The display unit is a device setting, since it's about how this person reads their kit, not a fact about the tank. Grading uses the canonical value, so a reading in range stays in range whatever it's shown as.

The ratios are where silent errors live. NO₃ is 4.427 times NO₃-N, so the same water reads 10 on one kit and 44 on another. Nitrite has its own ratio, 3.284. One meq/L is 2.8 dKH. An unknown unit throws instead of passing the number through, because an unconverted alkalinity is off by 2.8 times and still looks plausible on a chart. I caught myself quoting nitrate's 4.4 on the nitrite row, on a screen whose whole job is preventing unit mistakes. Both figures now come from constants pinned by tests.

Drift as the source of truth, with an outbox

The UI reads only from Drift. Every write goes into its table and into an outbox table in the same transaction, so nothing appears on screen without also being queued for the server.

await _db.transaction(() async {
  // ...the session row and its outbox entry first, then for each reading:
  await _db.into(_db.readings).insert(ReadingsCompanion.insert(
    id: id,
    tankId: draft.tankId,
    sessionId: Value(sessionId),
    parameterKey: entry.parameterKey,
    valueCanonical: canonical,
    enteredValue: entry.value, enteredUnit: entry.unit,
    measuredAt: draft.measuredAt,
    updatedAt: stamp,
  ));
  await _outbox.enqueue(entity: SyncEntity.readings, entityId: id, op: SyncOp.upsert,
      payload: {/* the same row as JSON */});
});

The outbox stores the payload rather than re-reading the row later, so an edit can't change what an earlier queued write meant. IDs are UUID v7 made on the device, so a reading can reference a tank that hasn't synced yet. Deletes set deleted_at, because a delta sync can't express a row that stopped existing.

The sync engine is written against a small SyncRemote interface and tested against a fake, on an in-memory SQLite database rather than a mock. It pushes before it pulls, parents before children. The pull asks for rows with updated_at after the stored cursor minus two seconds, because a transaction that began before the cursor can commit after it. The cursor comes from server rows, stamped by a Postgres trigger, never from the device clock, and a pulled row is skipped while the same row has an unpushed local edit. Drift reads DateTimes back in local time by default, so I set store_date_time_values_as_text, which keeps UTC as UTC.

What went wrong:

• Against a project that took fourteen seconds to answer auth, eight changes were dead-lettered and shown as refused by the server. They hadn't been. Each timeout counted as an attempt across launches and resumes, and after five the tank was abandoned; its parameter settings then pointed at a tank the server had never seen, row level security refused them, and they went too. Now being offline never uses up attempts, a pass stops before anything depending on an abandoned row, and dead letters have a "Try again".
• Sync only ran while the account screen was open, because only that screen watched the provider. It's now watched at the app root and invalidated on resume.
• The tank screen kept showing "not tested yet" after a test was logged, until a restart. The query watched only the settings table but attached the last reading from another one; Drift's readsFrom fixed it. The tests missed it because they called .first after writing. The new one subscribes first.

Row level security, briefly

Supabase only holds a copy for people who sign in, and row level security is the real boundary; the publishable key in the app authorises nothing on its own. Tanks carry an owner_id, and a tank_members table that every policy already reads through means sharing can come later without a migration. Every child table carries tank_id, so one pair of policies covers all of them:

do $$
declare t text;
begin
  foreach t in array array[
    'tank_parameter_config','test_sessions','readings','livestock',
    'task_templates','task_events','journal_entries','photos','cycle_logs'
  ] loop
    execute format($f$
      create policy %1$s_select on public.%1$s
      for select to authenticated
      using (tank_id = any (array(select private.accessible_tank_ids())))
    $f$, t);
    -- plus a matching %1$s_write policy using private.can_edit_tank(tank_id)
  end loop;
end $$;

The helpers are security definer functions in a private schema with an empty search_path, revoked from the API roles, which also breaks the infinite recursion of a tank_members policy that queries tank_members. auth.uid() is wrapped as (select auth.uid()), as the Supabase RLS docs recommend. A pgTAP suite simulates two users by setting request.jwt.claims, and an integration test runs the real sync code against a local Supabase stack and checks that a second account sees none of it.

What the app does for the people who use it: A free aquarium water test log app for iPhone.

FAQ

How do you calculate free ammonia from pH and temperature?

Compute pKa = 0.09018 + 2729.92 / T with T in kelvin, then the free fraction = 1 / (1 + 10^(pKa − pH)), and multiply total ammonia by it. At 25 °C pKa is about 9.25, so roughly 0.56% of total ammonia is un-ionised NH₃ at pH 7 and 5.4% at pH 8. The expression is for fresh water; in seawater the real fraction is slightly lower.

Should an untested value be stored as null or zero?

Neither. In Aquarium an untested parameter produces no reading row, and nulls appear only when rows are grouped into per-session views. Storing zero for "not tested" draws dips that never happened and makes rate-of-change checks compare against a value nobody measured.

How do you build offline-first sync with Drift and Supabase?

Make Drift the only thing the UI reads, and write every change to its table and to an outbox table in one Drift transaction. A sync engine pushes the outbox parents-first, then pulls rows whose server-stamped updated_at is newer than the last one it saw minus a short overlap, skipping rows with unpushed local edits. Client-generated UUIDs and deleted_at tombstones let both sides agree on what changed.

How does an app decide an aquarium is cycled?

Aquarium groups readings into test sessions and looks for two sessions in a row where ammonia and nitrite are at or below 0.25 ppm and nitrate is present. One such session is shown as "confirming", because a single clean result can be a misread.

How do you write Supabase RLS policies for tables that belong to a parent row?

Give every child table the parent's id, put the access check in a security definer function in a schema the API can't reach, and generate the same select and write policy for each table in a loop. Wrap auth.uid() as (select auth.uid()) and index the columns the policies filter on.

Server: Flask, PostGIS and a self-hosted ParkAPI. Phone: SwiftUI on iOS 17.

OpenStreetMap street parking is mostly a German dataset

My first plan was OpenStreetMap everywhere. Kerbside parking is tagged on the street itself, with keys like parking:left=lane and parking:right:fee=no (see Street parking on the OSM wiki). When I measured in September 2026, this was the share of drivable streets carrying any parking:* tag:

Fee sub-tags were on about a tenth of those. Berlin works: 64,229 kerb sides and 48,567 car parks from one Geofabrik extract. Elsewhere a tag-driven layer would be mostly blank, which reads as "no parking here". So outside Germany the street layer comes from municipal open data, which the city actually enforces.

Reading the tags has traps. The wiki deprecated the older parking:lane=* and parking:condition=* keys in December 2022 and asks for existing ones to be converted, so the normaliser reads both. parking:left=no is a value, not an absence: 43% of Berlin's tagged sides. And without closed_ways_are_polygons in its config, GDAL put closed amenity=parking ways in the lines layer, where my highway filter dropped them: Berlin had 42 car-park polygons instead of 63,294.

Deriving "likely free" from what a city charges for

Councils publish what they charge for, because that's what they enforce. Barcelona's surface parking dataset lists its blue, green and goods-delivery segments; Kraków publishes 23 paid-zone polygons and no kerbs. The complement is the free map: every drivable street inside the city boundary with nothing regulated near it.

CREATE TEMP TABLE regulated AS
SELECT geom FROM efp.street_parking
WHERE city_id = :'city' AND fee_source IN ('municipal_paid', 'municipal_free')
UNION ALL
SELECT geom::geography FROM efp.paid_zone WHERE city_id = :'city';  -- Kraków's polygons

-- ...
FROM osm_stage.streets_REGIONTAG s
CROSS JOIN (VALUES ('left'), ('right')) AS sides(side)
WHERE EXISTS (SELECT 1 FROM city_boundary b WHERE ST_Within(s.geom, b.geom))
  AND NOT EXISTS (
      SELECT 1 FROM regulated r
      WHERE ST_DWithin(efp.kerb_offset(s.geom, sides.side)::geography, r.geom, :clearance))
  AND s.highway IN ('residential', 'living_street', 'unclassified', 'tertiary', 'tertiary_link')
  AND lower(coalesce(s.access, '')) NOT IN ('private', 'no', 'customers')

Three of these are there because a looser version published something wrong.

Metres, not degrees. The first version buffered by 0.00025°. At Barcelona's latitude that's 27.8 m north–south but 20.8 m east–west, and 407 streets 21–25 m from a paid kerb went out as free. Casting to geography makes ST_DWithin measure in metres; :clearance is 25.

Test the kerb, not the centreline. efp.kerb_offset shifts the street 3 m to one side, working in EPSG:3857 and dividing the distance by cos(latitude) to undo Mercator's stretch. That line can sit closer to a paid kerb than the centreline, so it's the one tested.

Leave out roads with no parking. The first run turned 17,275 regulated segments into 10,842 free kerb sides, and the map showed dashed "likely free" lines down Avinguda Diagonal. Arterials have no regulated segments because nobody parks on them, so "outside every paid zone" came out true. Limiting the rule to residential, unclassified and tertiary roads dropped 3,156 sides, 29% of the layer. Service roads stay out: they're car-park aisles and driveways as often as public kerb.

Kraków's polygons feed the same rule: 21,255 free kerb sides, none within 25 m of a zone. A test samples 2,000 derived kerbs per city to assert it. Checking every row took over 150 seconds at 29,000 derived against 105,000 regulated, and a check nobody waits for is a check nobody runs.

Free and likely free are different values

The schema never stores a bare "free". Every row has a fee_state (FREE, PAID, CONDITIONAL, UNKNOWN) and a fee_source saying where it came from: municipal_free, osm_tag, operator_feed, municipal_paid_complement and municipal_outside_zone.

The last one came from Madrid, whose SER map service publishes 87,614 kerb bands. 53,158 are grey, a colour missing from the service's own legend. Sampling 300 bands of each colour against the SER boundary settled it: every blue and green band tested fell inside, no grey one did. So grey bands are published kerbs outside the paid zone: stronger than an inference from nothing, weaker than the council saying "free". I first stored them as municipal_paid_complement, and the overlap test failed, correctly: grey bands sit next to blue ones on the same street, which for a derived street would be a bug.

One function turns the pair into a claim, ordered by trust: a current count, a published fact, a schedule, an inference, an admitted gap.

switch (feeState, feeSource) {
case (.free, .municipalFree), (.free, .operatorFeed):
    return .cityFree
case (.free, .osmTag):
    return .signpostedFree
case (.free, .municipalOutsideZone), (.free, .municipalPaidComplement):
    // This is the inference, and it must never borrow a stronger phrasing.
    return .likelyFree
case (.free, _):
    // A free claim with no provenance is not one we will repeat.
    return .unknown
default:
    break
}

Charging hours the parser can't read resolve to "charged right now": wrong that way costs a walk, the other way a fine.

On the first build the inferred layer was mint and read as the same free as the confirmed green. Now it's teal and dashed, which says "not solid" before anyone reads the legend:

ForEach(model.streets) { street in
    MapPolyline(coordinates: street.coordinates)
        .stroke(street.claim.tint.opacity(0.85),
                style: street.claim.isInferred ? .inferredKerb : .kerb)
}

private extension StrokeStyle {
    static let kerb = StrokeStyle(lineWidth: 4, lineCap: .round, lineJoin: .round)
    /// Dashed: derived from an absence of regulation, not from a sign.
    static let inferredKerb = StrokeStyle(
        lineWidth: 4, lineCap: .butt, lineJoin: .round, dash: [3, 7])
}

Both hedged kinds draw the same dashed teal; the data keeps them apart.

Drawing kerbs with SwiftUI's Map

That ForEach is the whole renderer, and its cost is the count: a city-wide Barcelona viewport holds around 660 kerbs. The obvious fix is one MKMultiPolyline per style, about four overlays, but MapPolyline has no initialiser that takes one. So I rewrote the map as MKMapView in a UIViewRepresentable. It worked in the simulator and drew no tiles on a real device. I couldn't reproduce it, and a blank map is worse than a slow one, so I went back to SwiftUI's Map. What keeps it smooth:

• Measure first. The database answered in 7.6 ms and the endpoint in under half a second, so the stutter was on the phone.
• Fetch a ring, draw the screen. The app fetches 30% of the span beyond each edge, skips the request while the viewport stays inside it, and waits 250 ms for the camera to settle. Drawing is clipped to the viewport, about 60% fewer lines, and the array is reassigned only when visible IDs change: an identical array still makes SwiftUI diff every overlay.
• Slim payload. Street name, zone, capacity and source were 65% of the bytes and none is drawn, so the layer gets four fields per kerb and coordinates rounded to six decimals, about 10 cm. A city-wide response went from 575 KB to 359 KB.
• Nearest first. The query orders by sp.geom <-> centre with a limit of 1,500, so truncation eats the ring, not the middle of the screen.

One feature from the live API:

{
  "type": "Feature",
  "geometry": {
    "type": "LineString",
    "coordinates": [[2.174812, 41.403032], [2.174847, 41.403005], [2.174876, 41.402983]]
  },
  "properties": {
    "source_id": "complement-es-barcelona-885702924-left",
    "fee_state": "FREE",
    "fee_source": "municipal_paid_complement",
    "opening_hours": null
  }
}

A cap of 400 drawn kerbs left the edges of a Barcelona screen bare, and a driver can't tell a capped edge from a street with no parking, so it went.

València publishes individual spaces, 315,303 averaging 2.6 m, so 1,500 features covered a few blocks. ST_ClusterDBSCAN, partitioned by street, fee state and a grid of about 300 m, now merges adjacent bays into segments with a bay count: the same view went from 1,500 features and 453 KB to 582 and 135 KB. Without the grid, nameless paid bays chained into lines 25 km long. A polyline threaded through the bays zig-zagged across the street, since bays sit on both sides, so each cluster is drawn as the longest line across its convex hull.

Zoomed out past 0.02° of span, the kerb layer switches off and the gateway counts kerbs in roughly an 8×8 grid over the viewport, drawn as circles. These aren't MapKit annotation clusters: the phone never downloads the kerbs at that zoom. Circle size is logarithmic, because counts span four orders of magnitude and linear sizing pinned nearly every circle to the maximum.

Live counts go stale after 15 minutes

The old app read api.parkendd.de, which had stopped updating. Now I run my own ParkAPI v3 (MIT), pulling realtime data every 300 seconds into the same Postgres as my schema, so the gateway joins its parking_site table directly. The gateway decides freshness, so phone and server can't disagree:

STALE_AFTER = timedelta(minutes=15)

def freshness(updated_at: datetime | None) -> str:
    if updated_at is None:
        return 'none'
    age = datetime.now(timezone.utc) - updated_at
    return 'live' if age <= STALE_AFTER else 'stale'

for row in rows:
    row['freshness'] = freshness(row.get('realtime_updated_at'))
    # Keep the number, drop the claim that it is current.
    row['realtime_is_current'] = row['freshness'] == 'live'

ParkAPI's own public API drops realtime fields once they're too old. I keep the number and label it: a stale count shows grey as "N free when last seen", with its age. On 9 November 2026, 15 car parks within 2 km of central Basel had a current count.

Indigo's feed reported zero occupancy for all 558 French car parks, which naive arithmetic shows as empty, so realtime is off for it. And 28% of upstream ParkAPI converters were already dead when I set it up, so each source's last success and error live in a table.

Licences and gaps

OpenStreetMap data is ODbL (© OpenStreetMap contributors). Barcelona and València publish under CC BY 4.0, Madrid and Kraków under their own open-data terms, the French national base and Indigo under ODbL. Derived layers credit both the council and OSM, and the app shows these credits behind its info button.

Missing: an offline cache, address search, and Warsaw. Its city API timed out when I checked, and OSM had fee information on 0% of its central streets. Kerb lines show rules, not empty spaces.

What the app does for the people who use it: Free parking app for Europe: Easy Find Parking for iPhone.

FAQ

How complete is OpenStreetMap parking data in European cities?

Very uneven. When I measured in September 2026, the share of drivable streets with any parking:* tag was 99.9% in Berlin, 10% in Paris, 4% in Barcelona and 0.9% in Lisbon, and about a tenth of tagged streets had fee information. Outside Germany, municipal open data is usually the better source.

How do you find free street parking from a city's paid parking data?

Take the OpenStreetMap road network inside the city boundary and drop any street side within a clearance (25 m in Easy Find Parking) of a published paid segment or zone polygon. Limit it to residential, unclassified and tertiary roads, or arterials come out free, and label the result "likely free".

Should I buffer in degrees or metres in PostGIS?

Metres. On EPSG:4326 geometry, distances are in degrees, and a degree of longitude shrinks with latitude: 0.00025° is 27.8 m north–south but 20.8 m east–west in Barcelona. Cast to geography and ST_DWithin takes metres.

How do I draw thousands of polylines in a SwiftUI Map without lag?

SwiftUI's Map needs one MapPolyline per line and can't take an MKMultiPolyline, so the line count is the cost. Fetch a padded area, skip requests while the viewport stays inside it, debounce camera changes by about 250 ms, draw only what's visible and send only the fields you draw. Zoomed out, show area counts instead.

How do you know if a live car park count is still current?

Compare its timestamp with the server's clock. Easy Find Parking treats a count older than 15 minutes as stale: it keeps the number but shows it as "free when last seen" with its age, never as spaces available now.

Why artwork matching picks the wrong print

Before release I built a harness on a Mac that calls the same Vision APIs as the app: 9,903 cards indexed, 400 queries, half drawn on purpose from collector numbers that more than one print shares. Each query was a synthetic degradation of an official card image (perspective, blur, glare, colour cast, JPEG).

The last row changed the design. Even with the right collector number, artwork matching picks the right print 89.5% of the time, because alternate arts and higher-rarity parallels often share one number and one illustration. No embedding separates two prints of one picture, so the app asks which print, as it asks whether a card is foil. And since five candidates nearly always include the right card, the five-card sheet is the main flow, not an error state.

The embedding is VNGenerateImageFeaturePrintRequest, revision 2: 768 floats, about 9 ms an image. One option matters more than it looks:

static func featurePrint(of image: CIImage) -> [Float]? {
    let request = VNGenerateImageFeaturePrintRequest()
    request.imageCropAndScaleOption = .scaleFill
    try? VNImageRequestHandler(ciImage: image, options: [:]).perform([request])
    guard let observation = request.results?.first else { return nil }
    var vector = [Float](repeating: 0, count: observation.elementCount)
    _ = vector.withUnsafeMutableBytes { observation.data.copyBytes(to: $0) }
    return vector
}

static let artworkMatchingAvailable: Bool = {
    let probe = CIImage(color: .gray).cropped(to: CGRect(x: 0, y: 0, width: 64, height: 90))
    return featurePrint(of: probe) != nil
}()

The default, .centerCrop, cuts the top and bottom off a tall card: 82.4% against 93.2% for .scaleFill on the same 1,295-card index. The probe exists because feature prints fail in the Simulator ("Failed to create espresso context"). The app checks once and falls back to the collector number alone, as it would on any device without a usable neural engine.

Distance is not a confidence score

The obvious next step is a distance threshold. Measured, it says almost nothing: median distance was 0.450 when the top match was right and 0.420 when it was wrong. But distance does tell whether there is a card at all: photographed cards sat at a median of 0.459, a phone pointed at a laptop at 0.966. I found that out when the scanner, with no ceiling, turned a browser window into twenty-six confident entries. The ceiling is now 0.80, which keeps 99% of photographed cards and rejects 89% of everything else.

Reading the collector number

The number is unambiguous whenever it is legible, so most of the work went into legibility.

Drop soft frames. Between a handheld frame and a sharp one, the artwork gained 5.6 points and the collector number 46 (32.8% read against 78.5%). The gate is the variance of the Laplacian on a greyscale buffer of the rectified card. My first version chained Core Image filters, a Laplacian then a multiply blend, and returned negative variances: blend modes clamp and premultiply, they are not arithmetic.

Don't ask Vision to find the card. On iOS, VNDetectDocumentSegmentationRequest returned the card's text box at 0.96 confidence, and VNDetectRectanglesRequest found artwork panels, never the border. So the scanner draws a card-shaped guide, tries three crops around it and keeps whichever embeds closest to the index.

Read in passes, at full size. Downscaling crops is how my first benchmark reported an OCR accuracy of zero. VNRecognizeTextRequest runs over the whole card, then the top and bottom 22% enlarged 2.5 times, then three corners at 4 times if nothing turned up:

private func scan(_ image: CIImage, into found: inout Set<String>, minimumTextHeight: Float = 0.008) {
    let request = VNRecognizeTextRequest()
    request.recognitionLevel = .accurate
    request.usesLanguageCorrection = false   // these are codes, not words
    request.recognitionLanguages = ["en-US"]
    request.minimumTextHeight = minimumTextHeight   // the default floor skips the number
    try? VNImageRequestHandler(ciImage: image, options: [:]).perform([request])

    for observation in request.results ?? [] {
        for candidate in observation.topCandidates(2) {
            found.formUnion(PrintedNumber.extract(from: candidate.string))
        }
    }
}

The recognizer swaps look-alikes (S and 5, O and 0, B and 8), so readings are folded before comparing. That tolerance is what kept producing wrong additions. The fix was two keys: a loose one, padding removed, for finding candidates, and a literal one, padding and variant marks kept, for adding without asking. "45/195" fits a catalog "045/195", but it is also what "145/195" looks like with its first digit lost.

When the scanner adds and when it asks

Add without asking only when the artwork's first choice (or a card it can't tell apart from it) and a reading that spells that card's number literally name the same card, and nothing the artwork can't rule out shares that number. Everything else is the sheet. Trimmed from ScanPipeline.decide:

func blocks(_ card: CardRef) -> Bool {
    guard card.id != winner.id else { return false }
    guard baseName(card) != baseName(winner.card) else { return true }   // same card, other print
    guard let margin = policy.distinctParallelMargin, let mine = winner.distance,
          let theirs = distances[card.id] else { return true }
    return theirs < mine * (1 + margin)
}
if parallels.contains(where: blocks) { return .ambiguous(candidates: offered, reason: .parallelPrints, numbers: numbers) }
let artworkAgrees = winner.id == candidates[0].id
    || artworkTies(candidates[0], winner, policy.minimumRelativeMargin)
let byNumber = winner.numberMatched && artworkAgrees
    && (spelled(winner.card, literals) || unpadded)
guard byNumber else {
    return .ambiguous(candidates: ordered, reason: winner.numberMatched ? .numberDisagrees : .lowConfidence, numbers: numbers)
}
return .identified(winner)

A different card sharing the number stops blocking only if the artwork puts it at least 15% farther away. unpadded lets an old card printed "18/130" match a catalog "018/130", but only when it lands on the artwork's own first pick.

The rule took three rounds of adversarial review to reach, each reported bug reproduced against the real catalogs. The first confirmed 33 defects; the second found 12 new ones, 11 introduced by the fixes. As my commit message put it, a comparison built to find candidates was also allowed to add one. Adding on artwork margin alone went too: a card missing from the index still has a nearest neighbour that can be clearly ahead and wrong.

Before a silent add, a second text request also counts Han, kana and hangul characters, because artwork and number are identical across languages and each catalog holds one. English cards read 0 to 3, Japanese ones 37 to 188; the cut-off is 8.

Then I measured on 529 real photographs of cards, labelled against the catalog, with all five games installed (62,331 cards in one index) and the app's recognition code running on a Mac. Every silent add was checked by eye:

The gains came from the photos: a picked photo now skips the quality gates, since no better frame is coming; the number is read from the loosest crop when the tightest cut it off; and each crop is also embedded slightly blurred, because a holo's sparkle pulled matches away from the flat scans in the index (right card first: 377 to 397). The live camera path is still unmeasured; for that, the app keeps an on-device calibration log of each attempt and the card the user actually picked.

Keeping a 27,000-card index on the phone

Each game's index downloads separately, quantised to int8 with one scale per pack. On queries perturbed to the distance a handheld photo sits at, int8 and float16 returned the same card 99.8% of the time, for half the bytes. There's no approximate nearest-neighbour library: in the Mac harness, a brute-force scan of the largest index, 26,978 vectors, takes 1.6 ms widened to Float, but holds 83 MB. So the app memory-maps the int8 bytes and converts 512 rows at a time with vDSP_vflt8 and vDSP_distancesq: 5.6 ms, nothing resident. The scan runs only on a steady frame, so four milliseconds is invisible and 83 MB isn't. A pack from a different Vision revision is refused; its distances live in another space.

The index is built on a Mac and lags the catalog, so a clearly read number naming a card the artwork never offered goes to the top of the sheet, asked about and never added.

A ledger that never overwrites, and one price file for everyone

The collection is an append-only ledger table plus an items table derived from it in the same transaction. Removal is a tombstone; rebuild() replays the log. Replay needs an order every device agrees on, and the middle term of the sort key is a bug fix: the scanner adds a card and sets its finish within one millisecond, and a random event id sometimes sorted the edit first.

/// Creation sorts before every edit to the same item at the same instant.
var replayRank: Int {
    if case .added = self { return 0 }
    return 1
}

for record in records.sorted(by: { ($0.timestamp, $0.event.replayRank, $0.eventID)
                                 < ($1.timestamp, $1.event.replayRank, $1.eventID) }) {

It paid off in October. The upstream catalog renamed sets, card ids include the set name, and 1,323 cards in one game got new ids overnight, 222 more across the others. Copies saved under old ids dropped off the collection screen. The fix is an alias table read in memory; the log stays as written.

Prices are one binary file per game, the same bytes for every user, so a request says nothing about what anyone owns. Names are content-addressed and the manifest is written last, so a client never sees half an update. Prices are integer cents, with a sentinel so a $0.00 promo isn't an unpriced card. Each carries the day it was captured, and past PriceProvenance.staleAfterDays (7) the portfolio headline says "These prices are 2 weeks old" instead of presenting an old total as current.

What the app does for the people who use it: Scan trading cards and see what they're worth with Foilcase.

FAQ

How do you tell apart card printings that share the same artwork?

Mostly not from the image: in my pre-release harness, artwork matching picked the right print 89.5% of the time even when given the correct collector number. Foilcase reads the number with Vision text recognition and, when other prints share it, shows the candidates and asks.

Is VNGenerateImageFeaturePrintRequest good enough for on-device image recognition?

For retrieval, yes, with no model to ship: the right card was in the top five 99.8% of the time on sharp synthetic frames of a 9,903-card index. Use .scaleFill, and test on a device, because it doesn't run in the Simulator.

Do I need an approximate nearest neighbour library for on-device image search?

Not at tens of thousands of vectors. A brute-force Accelerate scan over 26,978 feature prints took 1.6 ms on a Mac in Float, or 5.6 ms as memory-mapped int8, which avoids holding 83 MB in memory.

Can embedding distance be used as a confidence score?

Not between similar images: median distance was 0.450 for correct matches and 0.420 for wrong ones. It does separate cards (0.459) from non-cards (0.966), so Foilcase uses it only as a 0.80 ceiling.

How do you read small printed numbers with VNRecognizeTextRequest?

Lower minimumTextHeight, turn off language correction, never downscale the crop, and add passes over enlarged strips and corners. Rejecting blurry frames first matters most: it took collector-number accuracy from 32.8% to 78.5% in my harness.

Why store a collection as an append-only ledger?

Nothing is overwritten, so a mis-tap or a bug can't destroy data: removal is a tombstone and the item table is rebuilt from the log. Changed upstream ids resolve through an alias table at read time, without touching user data.

The plans below come from running the app's planning package, a Swift package with no UI, on its Beginner Country Loaf recipe.

The fermentation model is one formula

Proofday's model says every 7 °C doubles or halves fermentation time, relative to 24 °C:

// FermentationConfig.swift
public var referenceTemperatureC: Double = 24
public var degreesPerDoubling: Double = 7
public var trustedTemperatureRangeC: ClosedRange<Double> = 16...30

// FermentationModel.swift
public func temperatureFactor(celsius: Double) -> Double {
    let t = clamp(temperatureC: celsius).value
    return pow(2, (config.referenceTemperatureC - t) / config.degreesPerDoubling)
}

Bulk is 5 hours at 24 °C with 20% levain, so 18 °C gives a factor of 1.81 and about 9 hours, and 30 °C gives 0.55 and 2.8 hours. Outside 16–30 °C the input is clamped and the plan carries a warning, so 34 °C plans exactly like 30 °C rather than trusting an exponential that far out.

The model's other constants, down to the starter peak table (5 to 14 hours at 24 °C, from 1:1:1 to 1:10:10 feeds), live in the same struct. Its doc comment calls them "starting heuristics, not lab science".

Learning from logged bakes

When a starter peaks or a bulk ends, the app folds actual over predicted into a per-starter moving average:

public mutating func record(actual: TimeInterval, baselinePrediction: TimeInterval,
                            config: FermentationConfig = .standard) -> Bool {
    guard actual > 0, baselinePrediction > 0 else { return false }
    let ratio = actual / baselinePrediction
    guard config.correctionSampleSanityRange.contains(ratio) else { return false }
    let alpha = config.correctionSmoothing
    let next = alpha * ratio + (1 - alpha) * value
    value = min(max(next, config.correctionRange.lowerBound), config.correctionRange.upperBound)
    sampleCount += 1
    return true
}

α is 0.3, the factor stays within 0.6–1.6, and a ratio outside 0.25–4 counts as a logging mistake. The part that matters is the argument name. Predictions are already multiplied by the factor, so a sample has to be compared with the uncorrected baseline. Compare with the corrected one and the average settles at the square root of the true factor: a starter that really takes 1.44 times as long gets learned as 1.2. So each feeding and each plan stores its uncorrected estimate up front.

Planning backwards is a shortest path

A recipe is a chain of typed steps. Each resolves into a minimum, ideal and maximum length, hands-on minutes, and the moments the baker acts: the step's start, each fold, and the oven preheat as a negative offset from the bake. Bulk doesn't flex at plan time; the aliquot jar decides when it really ends. The cold proof (8 to 24 hours), autolyse, bench rest, cooling and the levain do.

Rounding every length to a 5-minute grid turns the search into a dynamic program. The state is "step i starts at time t", filled in from the ready time backwards:

for i in stride(from: n - 1, through: 0, by: -1) {
    var next: [Int: Node] = [:]
    for t in levels[i + 1].keys.sorted(by: >) {
        let node = levels[i + 1][t]!
        for (vi, variant) in steps[i].enumerated() {
            let s = t - variant.duration
            if s < earliestStart { continue }
            let v = violations(of: variant, at: s, anchorExempt: false)
            if hard && v > 0 { continue }
            let cost = node.cost + variant.cost + Double(v) * violationCost
            if let existing = next[s], existing.cost <= cost { continue }
            next[s] = Node(cost: cost, violations: node.violations + v, link: t, variant: vi)
        }
    }
    if next.isEmpty { return nil }
    levels[i] = next
}

levels[n] holds the ready time at cost zero. A variant is one layout of a step: a length, plus a feed ratio for the levain or a preheat length for the bake. Keeping only the cheapest path into each boundary is exact because a step's cost and quiet-hours check depend only on its own start and length. On a tie the later start wins, so you wait less.

Quiet hours default to 23:00–07:00, and staying out of them has two shapes. An action is a point and may sit on the boundary, so a fold at 7:00 is fine. Hands-on minutes are a span and may not overlap at all, so a 15-minute shape has to start by 22:45.

Preferences are just prices

There's no rule saying "stretch the cold proof first". There are costs:

public var costPerMinute: Double {
    switch self {
    case .coldProof: 0.05
    case .levain: 0.15
    case .autolyse, .rest: 0.2
    case .cool, .roomProof: 0.3
    case .benchRest: 0.5
    default: 1
    }
}
// FermentationConfig
public var feedRatioSwitchCost: Double = 20
public var quietHoursViolationCost: Double = 10_000

A cold proof minute away from the ideal is the cheapest thing on the list, a third of a levain minute. A different feed ratio costs 20, as much as moving the cold proof 400 minutes. So a plan bridges the night with the fridge when it can, and reaches for a 1:5:5 or 1:10:10 overnight feed when that's cheaper.

For the Beginner Country Loaf at 23 °C, ready Saturday at 10:00, the 12 steps expand to 182 variants, 70 of them for the levain alone:

Fri 07:10  levain       465 min  1:2:2
Fri 14:55  autolyse      60 min
Fri 15:55  mix           15 min
Fri 16:10  bulk         330 min  folds 16:40, 17:10, 17:40, 18:10
Fri 21:40  preshape       5 min
Fri 21:45  bench rest    30 min
Fri 22:15  shape         15 min
Fri 22:30  cold proof   555 min  (ideal 720)
Sat 07:45  bake          20 min  preheat from 07:00
Sat 08:05  lid off       25 min
Sat 08:30  cool          90 min  (ideal 120)
Sat 10:00  ready

The preheat can't start before 7:00, which pins the bake and cuts cooling to 90 minutes; the plan says so in a note. On my M1 Pro, in a release build, that takes about a millisecond. The app still solves in a detached task, since the setup screen re-plans on every input change.

Rough edges: windows longer than two hours are searched in 15-minute steps, so the cold proof can't be 565 minutes and the levain starts at 7:10 rather than 7:00. And the cold proof used to stop at 16 hours, the figure I started from, which made dinner-time bread impossible with the default quiet hours. It now goes to 24: ready at 19:00 on Saturday means shaping at 22:45 on Friday and a 17 h 15 min proof.

Saying no, with a reason and a better time

When the hard solve fails, the planner works out why, in order: the target has passed, the step minimums don't fit, the target is inside quiet hours, or some action would be. For that last case it reruns the DP in soft mode, where a violation costs 10,000 instead of being forbidden, and reports the first action that lands in quiet hours. Then it walks a 15-minute grid outward, up to 48 hours each way, until a ready time solves.

From the package:

• Saturday 9:00, asked on Thursday: the first violation is the preheat at 6:10 AM. Nearest: 9:30.
• Saturday 10:00, asked Friday at 8 PM: the bake needs at least 21 h 20 min. Nearest: Sunday 9:30.
• Sunday 9:30, asked Saturday at noon: shaping would land at 11:30 PM. Nearest: Monday 9:30. With "My starter is already ripe" on, Sunday 9:30 works, shaping at 7:30 PM.

The third looked like a bug. It isn't: with a levain to build, the earliest Saturday shape is about half an hour too late, and mixing on Sunday morning puts the bread after 11 PM. These refusals took roughly 3 to 13 ms, mostly the search for alternatives.

Re-planning while the dough is out

Done, +15 min and Need more time re-run the solver forwards from the current step, in soft mode, with one more price: each minute the ready time drifts from the promise costs 1, against 0.05 for a cold proof minute. In the plan above, asking for 30 more minutes of bulk at 9:30 PM keeps 10:00 and shortens the cold proof to 525 minutes. Asking for 45 can't be absorbed, because shaping would run from 23:00 to 23:15. The plan keeps 10:00 and flags that action as inside quiet hours rather than moving the bread.

Notifications, Live Activities and widgets

Every pending action is a local notification, rescheduled after any change. The triggers are UNTimeIntervalNotificationTrigger, elapsed seconds rather than calendar components, so a DST change can't move an absolute moment. A time-zone change re-solves the plan, since quiet hours follow the wall clock. Done, +15 min and Snooze 5 min carry no .foreground option, so iOS hands them to the app in the background.

Live Activities were the awkward part. One lasts up to eight hours, twelve on the Lock Screen, and Activity.request only works while the app is in the foreground. The Saturday plan runs almost 27 hours. So:

static let startWindow: TimeInterval = 7 * 3600

func sync(planID: UUID, schedule: BakeSchedule, presenter: ActionPresenter, now: Date = .now) async {
    guard !schedule.isComplete, let state = Self.state(for: schedule, presenter: presenter, now: now) else {
        await end(planID: planID)
        return
    }
    let content = ActivityContent(state: state, staleDate: state.nextDate.addingTimeInterval(30 * 60), relevanceScore: 100)
    if await Self.update(planID: planID, content: content) { return }
    guard ActivityAuthorizationInfo().areActivitiesEnabled,
          state.nextDate.timeIntervalSince(now) < Self.startWindow else { return }
    _ = try? Activity.request(
        attributes: BakeActivityAttributes(planID: planID, recipeName: schedule.recipeName),
        content: content, pushType: nil)
}

sync runs after every plan change and whenever the app comes to the foreground. It updates a running activity, or starts one when the next action is under seven hours away, inside the eight-hour limit. There's no push server, so the content changes only when the app's code runs, but the countdown keeps moving because it's Text(timerInterval:), drawn by the system. The catch, stated in the user docs: it appears once you open the app within seven hours of a step. iOS 26 added a request that takes a start date and starts the activity with the app in the background. Proofday supports iOS 17 and doesn't use it.

Its Done and +15 buttons are LiveActivityIntents, which run in the app's process, through a static bridge the app delegate fills at launch. Under Swift 6, Activity isn't Sendable, so its handles stay inside nonisolated helpers.

Widgets never open SwiftData: the app writes a Codable snapshot of the next seven actions to the App Group, and the timeline adds an entry as each comes due, so the Next bake step widget advances on its own.

App Attest for the one server call

Crumb Check, a photo analysis of the cut loaf, is the only server feature: a small proxy in front of a Claude model. Each install makes a key with DCAppAttestService and has Apple attest it once. After that, every request carries an assertion over a single-use challenge plus the SHA-256 of the body, and the server checks signature, counter and app ID (Apple's overview). It allows 30 checks per install per day and stores only public keys, challenges and counters.

What the app does for the people who use it: Sourdough schedule planner that works back from bread time.

FAQ

How do you schedule tasks backwards from a deadline with time windows?

Round durations to a grid and run a dynamic program from the deadline back: the state is "step i starts at time t", each step offers one choice per allowed length, choices that put an action in a blocked window are dropped, and the cheapest path into each boundary is kept. Proofday does this on a 5-minute grid.

How does Proofday estimate fermentation time at different temperatures?

It multiplies a duration at 24 °C by 2^((24 − T) / 7), so every 7 °C cooler doubles it: a 5-hour bulk becomes about 9 hours at 18 °C. It's trusted between 16 and 30 °C, and a per-starter factor learned from logged bakes scales it.

When can an iOS app start a Live Activity?

With Activity.request, only while the app is in the foreground, or from a LiveActivityIntent. From iOS 26 an app can also schedule one for a start date. A Live Activity lasts up to eight hours, then can stay on the Lock Screen for up to four more.

How do you keep local notifications correct across daylight saving time?

Use UNTimeIntervalNotificationTrigger with the seconds until the absolute moment, not calendar components, so a clock change can't shift it. If times follow the wall clock, re-plan and reschedule on NSSystemTimeZoneDidChange and UIApplication.significantTimeChangeNotification.

How do you learn a correction factor from logged data without bias?

Average the ratio of actual duration to the uncorrected prediction and multiply predictions by the result. Averaging against the already-corrected prediction settles at the square root of the true factor. Proofday uses an exponential moving average with weight 0.3, clamped to 0.6–1.6.

What should a scheduler do when a deadline is impossible?

Say why and offer the nearest time that works. Proofday finds the offending action by re-running its solver with quiet-hour violations penalised instead of forbidden, then searches a 15-minute grid up to 48 hours either side for the closest feasible ready time.