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:
parent
57c0eeadaf
commit
040f15a898
131 changed files with 19855 additions and 20 deletions
100
packages/commons_core/lib/src/clock/hlc.dart
Normal file
100
packages/commons_core/lib/src/clock/hlc.dart
Normal 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];
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue