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];
}