feat(block1): inventory walking skeleton + first quick-add slice

Stand up the Tanemaki monorepo and the first end-to-end vertical slice of
Block 1 (offline, encrypted inventory): add a seed → see it in a categorized,
searchable list → it persists → reopen and it's still there.

Architecture (state management like G1nkgo, adapted to Tane's reality):
- flutter_bloc (Cubit-first), but the encrypted Drift DB is the single source
  of truth; cubits stream from repositories (no hydrated_bloc/Hive, which would
  write plaintext at rest).
- get_it composition root; go_router; slang i18n (ES/EN, Weblate-friendly JSON).

Workspace & core:
- pub workspace: packages/commons_core (pure Dart) + apps/app_seeds (Flutter).
- commons_core primitives: UUIDv7 IdGen, Hybrid Logical Clock, Quantity value
  type (+ plant-aware QuantityKind), IdentityService root-seed stub.

Data & security:
- Drift schemaVersion=1 with all 10 Block-1 tables + common CRDT columns
  (HLC updated_at, last_author, tombstones); Movement append-only.
- SQLCipher via an injectable executor that refuses to open a plaintext DB;
  DB key + root seed in the OS keystore (separate secrets).
- Exported drift_schema_v1.json + migration scaffold.

Tests (near-TDD; nothing merges without tests):
- commons_core units (24), Drift migration test, "no plaintext at rest"
  security guard (runs where SQLCipher is present, skips otherwise),
  repository, widget, full quick-add flow, file-reopen persistence, and a
  no-hardcoded-strings i18n guard. GitLab CI: format + analyze + test + coverage.

Follow-on Block-1 stories (item detail/edit, species catalog, germination UI)
and all of Block 2 remain out of scope.
This commit is contained in:
vjrj 2026-07-07 15:16:14 +02:00
parent 57c0eeadaf
commit 040f15a898
131 changed files with 19855 additions and 20 deletions

View file

@ -0,0 +1,100 @@
import 'package:equatable/equatable.dart';
/// A Hybrid Logical Clock timestamp (Kulkarni et al.).
///
/// Combines a physical wall-clock component ([millis]) with a monotonic
/// [counter] and a [nodeId] tiebreaker. It is the `updated_at` stamp on every
/// mutable row and drives last-writer-wins merges across devices, staying
/// monotonic even when the wall clock jumps backwards.
///
/// [pack] produces a fixed-width, lexicographically-sortable string so it can
/// be stored in a `TEXT` column and ordered with a plain SQL `ORDER BY`.
class Hlc extends Equatable implements Comparable<Hlc> {
const Hlc({
required this.millis,
required this.counter,
required this.nodeId,
});
/// The initial clock for [nodeId], before any event.
const Hlc.zero(String nodeId) : this(millis: 0, counter: 0, nodeId: nodeId);
/// Physical time in milliseconds since the Unix epoch.
final int millis;
/// Logical counter, bumped when two events share the same [millis].
final int counter;
/// Stable identifier of the node/device that issued this stamp.
final String nodeId;
static const _millisDigits = 15; // good until year ~5138
static const _counterDigits = 5; // 99999 events within one millisecond
/// Issues the next local timestamp given the current wall clock [wallMillis].
///
/// Monotonic: if the wall clock is behind our last stamp, we keep our
/// [millis] and bump the [counter] instead of moving time backwards.
Hlc localEvent(int wallMillis) {
final newMillis = millis > wallMillis ? millis : wallMillis;
final newCounter = newMillis == millis ? counter + 1 : 0;
return Hlc(millis: newMillis, counter: newCounter, nodeId: nodeId);
}
/// Merges an incoming [remote] stamp with the current wall clock, producing
/// the next local timestamp (used when receiving a peer's write).
Hlc receiveEvent(Hlc remote, int wallMillis) {
final newMillis = [
millis,
remote.millis,
wallMillis,
].reduce((a, b) => a > b ? a : b);
final int newCounter;
if (newMillis == millis && newMillis == remote.millis) {
newCounter = (counter > remote.counter ? counter : remote.counter) + 1;
} else if (newMillis == millis) {
newCounter = counter + 1;
} else if (newMillis == remote.millis) {
newCounter = remote.counter + 1;
} else {
newCounter = 0;
}
return Hlc(millis: newMillis, counter: newCounter, nodeId: nodeId);
}
/// A fixed-width, lexicographically-sortable encoding: `millis:counter:node`.
String pack() {
final m = millis.toString().padLeft(_millisDigits, '0');
final c = counter.toString().padLeft(_counterDigits, '0');
return '$m:$c:$nodeId';
}
/// Parses a string produced by [pack].
factory Hlc.parse(String packed) {
final parts = packed.split(':');
if (parts.length < 3) {
throw FormatException('Not a packed HLC: "$packed"');
}
return Hlc(
millis: int.parse(parts[0]),
counter: int.parse(parts[1]),
// nodeId may itself contain ':', so re-join the remainder.
nodeId: parts.sublist(2).join(':'),
);
}
@override
int compareTo(Hlc other) {
final byMillis = millis.compareTo(other.millis);
if (byMillis != 0) return byMillis;
final byCounter = counter.compareTo(other.counter);
if (byCounter != 0) return byCounter;
return nodeId.compareTo(other.nodeId);
}
@override
String toString() => pack();
@override
List<Object?> get props => [millis, counter, nodeId];
}

View file

@ -0,0 +1,18 @@
import 'dart:math';
import 'dart:typed_data';
/// Returns [length] cryptographically-random bytes.
///
/// Defaults to [Random.secure]. A seeded [Random] may be injected in tests for
/// reproducibility never do that in production code, as it is not secure.
Uint8List randomBytes(int length, {Random? random}) {
if (length < 0) {
throw ArgumentError.value(length, 'length', 'must be non-negative');
}
final rng = random ?? Random.secure();
final out = Uint8List(length);
for (var i = 0; i < length; i++) {
out[i] = rng.nextInt(256);
}
return out;
}

View file

@ -0,0 +1,24 @@
import 'dart:math';
import 'dart:typed_data';
import '../crypto/random_bytes.dart';
/// Creates the user's root identity secret.
///
/// One identity == one Duniter/Ğ1-style root seed. From it the app will later
/// *derive* a secp256k1 subkey for Nostr transport and expose a printable
/// recovery QR. This service only produces the seed bytes; derivation and
/// backup are separate, later stories (see docs/design/backup-and-recovery.md).
class IdentityService {
IdentityService({Random? random}) : _random = random;
/// Injected only in tests (seeded, reproducible). Production uses a CSPRNG.
final Random? _random;
/// Length of the root seed in bytes (256-bit).
static const int rootSeedLengthBytes = 32;
/// Generates a fresh root seed the ONE secret the user backs up.
Uint8List generateRootSeed() =>
randomBytes(rootSeedLengthBytes, random: _random);
}

View file

@ -0,0 +1,16 @@
import 'package:uuid/uuid.dart';
/// Generates client-side, time-sortable row identifiers (UUIDv7).
///
/// Every mutable row in the model is keyed by a client-generated UUIDv7
/// never an auto-increment (which would collide across peers). UUIDv7 embeds a
/// millisecond timestamp in its most-significant bits, so lexical order
/// approximates creation order, which suits CRDT sync and time-ordered queries.
class IdGen {
IdGen({Uuid? uuid}) : _uuid = uuid ?? const Uuid();
final Uuid _uuid;
/// A fresh UUIDv7 string, e.g. `018f1a2b-...-7...-...`.
String newId() => _uuid.v7();
}

View file

@ -0,0 +1,67 @@
import 'package:equatable/equatable.dart';
/// Coarse groups used by the UI to suggest relevant [QuantityKind]s for a
/// species/family. Purely presentational never forces a choice.
enum QuantityGroup { informal, plantForm, precise }
/// A stable, extensible, i18n vocabulary for *rough, human* seed amounts.
///
/// Values go deliberately beyond kitchen measures: seeds are counted in the
/// forms the plant gives them (a cob, a pod, a flower head). The display label
/// is localized from [name] so the enum name is the stable storage key and
/// must never be renumbered or reused (see data-model §5 migration rules).
enum QuantityKind {
// Informal / generic
aFew(QuantityGroup.informal),
some(QuantityGroup.informal),
plenty(QuantityGroup.informal),
handful(QuantityGroup.informal),
pinch(QuantityGroup.informal),
jar(QuantityGroup.informal),
packet(QuantityGroup.informal),
// Plant-form natural units
cob(QuantityGroup.plantForm),
head(QuantityGroup.plantForm),
pod(QuantityGroup.plantForm),
ear(QuantityGroup.plantForm),
fruit(QuantityGroup.plantForm),
bulb(QuantityGroup.plantForm),
tuber(QuantityGroup.plantForm),
seedHead(QuantityGroup.plantForm),
bunch(QuantityGroup.plantForm),
// Precise
grams(QuantityGroup.precise),
count(QuantityGroup.precise);
const QuantityKind(this.group);
final QuantityGroup group;
}
/// A quantity held or moved: a qualitative [kind], plus an optional [precise]
/// amount (grams / seed count) and an optional free-text [label] for rough
/// amounts no [kind] captures. Shared value type used by both Lot and Movement.
class Quantity extends Equatable {
const Quantity({required this.kind, this.precise, this.label});
final QuantityKind kind;
/// Optional precise amount, meaningful for [QuantityGroup.precise] kinds.
final double? precise;
/// Optional free text ("half a jam jar") when no [kind] fits well.
final String? label;
bool get isPrecise => precise != null;
Quantity copyWith({QuantityKind? kind, double? precise, String? label}) {
return Quantity(
kind: kind ?? this.kind,
precise: precise ?? this.precise,
label: label ?? this.label,
);
}
@override
List<Object?> get props => [kind, precise, label];
}