sync

type AckMarker ¶

type AckMarker struct {
	// Cursor is the per-origin-device transport cursor this device has pulled
	// AND consumed (device_id -> highest contiguous Seq). Pull rows only; the
	// push watermark is carried separately by PushedThroughSeq.
	Cursor map[string]int64 `json:"cursor"`
	// DeviceID is the acking device; it must equal the object key's device id.
	DeviceID string `json:"device_id"`
	// HLCWatermark is this device's current HLC clock (state.CurrentHLC): after a
	// clean cycle it is at or above every event HLC the device has applied, so
	// everything at or below it from other devices has been consumed here. It is
	// the value a compactor mins over to floor tombstone GC.
	HLCWatermark int64 `json:"hlc_watermark"`
	// ProducedAt is the HLC at which this marker was produced. In v1 it equals
	// HLCWatermark (both are the current non-minting HLC read); it is kept
	// distinct so a future minted-timestamp variant does not change the wire tag.
	ProducedAt int64 `json:"produced_at_hlc"`
	// PushedThroughSeq is this device's push watermark: the highest local Seq it
	// has published to the hub. A clean-cycle ack has this equal to local max
	// Seq, which is what makes the HLCWatermark a sound tombstone clock.
	PushedThroughSeq int64 `json:"pushed_through_seq"`
	// Sig is the Ed25519 signature over the canonical payload (all fields except
	// Sig), domain AckSignatureDomain.
	Sig string `json:"sig"`
	// V is the marker version.
	V int `json:"v"`
	// WorkspaceID binds the marker to its workspace.
	WorkspaceID string `json:"workspace_id"`
}

AckMarker is one device's signed sync acknowledgement (P4-SYNC-06). Fields are declared in alphabetical json-tag order so the marshaled document matches the canonical signature payload field-for-field (Go marshals structs in declaration order and maps with sorted keys), mirroring RetentionManifest.

func ParseAckMarker(raw []byte) (AckMarker, error)

type ApplyStats ¶

type ApplyStats struct {
	// Quarantined counts events recorded as conflicts instead of applied
	// (skew quarantine, hash-chain break, verification/divergence failure).
	Quarantined int
	// CursorHeld is true when at least one device's safe cursor stopped short
	// of that device's highest batch Seq — either a transiently-held event
	// (skew/hash-chain, re-delivered next pull) or a Seq gap on the hub.
	CursorHeld bool
}

ApplyStats reports what a single ApplyEvents batch did NOT apply. A non-zero Quarantined or a true CursorHeld means the local replica's derived state may be missing references other devices still rely on, so mark-and-sweep consumers (hub gc, P6-HUB-01) must refuse to sweep this cycle.

type BlobInfo ¶

type BlobInfo struct {
	Key          string
	LastModified time.Time
}

BlobInfo describes one blob on the hub: its sha256 hex key and the hub-reported creation/modification time (zero when the backend cannot provide one). P6-HUB-01: GC uses LastModified for an age grace window.

type ChainAnchor ¶

type ChainAnchor struct {
	DeviceID    string `json:"device_id"`
	Seq         int64  `json:"seq"`
	ContentHash string `json:"content_hash"`
	HLC         int64  `json:"hlc"`
}

ChainAnchor is one origin device's hash-chain anchor: the content hash of the LAST event covered by the snapshot for that device (seq = floor-1). A snapshot-bootstrapped device has no event rows below the floor, so the prev-hash verification of the first post-floor event needs this anchor as its fallback predecessor.

type ConflictRecord ¶

type ConflictRecord struct {
	NamespaceID string
	Type        string
	Details     string // details_json
}

ConflictRecord is a conflict Decide wants recorded, as plain data. The impure step maps it to tx.InsertConflict; the pure fold ignores conflicts (they do not change the namespace projection).

type ConflictResolvedPayload ¶

type ConflictResolvedPayload struct {
	ConflictID  string `json:"conflict_id"`
	NamespaceID string `json:"namespace_id,omitempty"`
	Type        string `json:"type"`
	DetailsJSON string `json:"details_json"`
	Action      string `json:"action"` // keep-local | keep-remote | keep-both
}

ConflictResolvedPayload carries a conflict.resolved event (PROD-06): the user's local resolution decision is audited and synced so every device sees the same outcome and the open-conflict count converges. ConflictID and NamespaceID are the origin device's local row ids (per-device, NOT stable across devices), retained only for display/audit; the apply handler matches on the stable (type, details_json) fingerprint instead (P5-SYNC-02).

type Cursor ¶

type Cursor map[string]int64

Cursor is the sync transport cursor (P5-SYNC-01): for each origin device on the hub, the highest per-device sequence number such that every event with Seq <= it has been pulled AND consumed (applied, deduped, or permanently quarantined). It is deliberately decoupled from the HLC, which remains the apply-ordering key only: every device's own event stream is gapless in Seq (UNIQUE events(device_id, seq), assigned in the same transaction as the HLC), so a per-device Seq cursor can never skip an event no matter how late it lands on the hub — the "offline device forgot to push, syncs late" scenario an HLC watermark permanently stranded. A device absent from the map has cursor 0 (pull from the beginning).

func ApplyEvents(ctx context.Context, st *state.Store, events []state.Event) (Cursor, error)

func (c Cursor) After(deviceID string) int64

type Decision ¶

type Decision struct {
	Mutations []Mutation
	Conflicts []ConflictRecord
}

Decision is the pure result of reconciling one event against a Projection: the intended namespace-map mutations plus the conflicts to record. No database access, no I/O, no *state.Tx.

func Decide(proj Projection, event state.Event) (Decision, error)

type DeviceKeyGrant ¶

type DeviceKeyGrant struct {
	Epoch      int64  `json:"epoch"`
	KID        string `json:"kid,omitempty"` // KIDForWCK of the wrapped key (P6-SEC-02); "" on legacy grants
	Recipient  string `json:"recipient"`     // age X25519 recipient the WCK is wrapped to
	WrappedKey string `json:"wrapped_key"`   // base64(age.Encrypt(wck, recipient))
}

DeviceKeyGrant carries a device.key.granted event (P4-SEC-07): a Workspace Content Key for an epoch, age-wrapped to a single approved device's X25519 recipient. Grant events ride the hub event log as PLAINTEXT (the decorator passes them through unencrypted) because their payload is already asymmetrically wrapped — the hub cannot decrypt the WCK without the recipient's private key. A newly-approved device ingests grants for every held epoch on its first pull so it can decrypt the entire namespace-map history.

type DraftSnapshotPayload ¶

type DraftSnapshotPayload struct {
	Path      string `json:"path"`
	BlobRef   string `json:"blob_ref"`
	ByteSize  int64  `json:"byte_size"`
	FileCount int64  `json:"file_count"`
}

DraftSnapshotPayload carries a draft.snapshot.created event's content-addressed blob reference and limits (DRAFT-02).

type EncryptedHub ¶

type EncryptedHub struct {
	Hub     Hub
	Keyring WorkspaceKeyring
	// Verify checks a grant carrier event's signature/trust before its WCK is
	// ingested (P6-SEC-01). nil disables the check (used by unit tests that
	// exercise decryption only). hubFromOptions wires it to
	// (*state.Store).VerifyRemoteEvent so the trust regime is identical to the
	// apply path.
	Verify func(ctx context.Context, ev state.Event) error
	// Stats, when non-nil, is populated by Pull with observability about the
	// raw batch (P6-SEC-02). RawSeen is the number of objects the backend
	// returned before any decrypt/skip/truncate — the founder/join gate uses
	// it to distinguish a genuinely empty hub (found here) from a populated
	// hub whose events this device cannot yet decrypt (a joiner awaiting its
	// grant, which must NOT self-found). It is also the seam later cursor and
	// GC work (P6-HUB-01/SEC-03/SYNC-02) will read.
	Stats *PullStats
	// MissingKeyWait records that an event sealed under (epoch, kid) was found
	// with no held key, and returns the STABLE first-seen time of that missing
	// key — the start of its grace window (P6-SEC-03). hubFromOptions wires it
	// to (*state.Store).NoteMissingKeyGrant. nil disables grace expiry
	// entirely: a missing key truncates forever (the pre-P6-SEC-03 behavior,
	// kept for unit tests that exercise the truncate contract in isolation).
	MissingKeyWait func(ctx context.Context, epoch int64, kid string) (time.Time, error)
	// GraceWindow bounds how long a missing (epoch, kid) may keep truncating
	// the pull before its events are handed to the undecryptable quarantine so
	// the cursor can advance (P6-SEC-03). Within the window the grant is
	// presumed in flight (truncate = retry next sync); past it the wedge is
	// treated as permanent-until-regrant: the still-encrypted carrier is
	// forwarded, ApplyEvents quarantines it, and a later grant recovers it via
	// ReplayUndecryptableConflicts. Zero means expire immediately (quarantine
	// on first sight); only meaningful when MissingKeyWait is non-nil. The
	// same window bounds the unknown-envelope-version defer (P6-SYNC-02),
	// clocked by NoteSkipped's stable first-seen.
	GraceWindow time.Duration
	// NoteSkipped durably records an event Pull drops from the batch
	// (P6-SYNC-02: unknown envelope version, retired enc.v1, anti-downgrade
	// plaintext) and returns the STABLE first-seen time of the (event,
	// reason) — the grace clock for the recoverable unknown-version class.
	// hubFromOptions wires it to (*state.Store).NoteSkippedEvent; the rows
	// surface in status/doctor, gate hub gc, and clear when the event
	// finally applies. nil keeps skips log-only (unit tests).
	NoteSkipped func(ctx context.Context, ev state.Event, reason string) (time.Time, error)
}

EncryptedHub is a Hub decorator that envelope-encrypts the namespace-map event log at the hub boundary (P4-SEC-02 / P4-SEC-07). It wraps a backend Hub (FileHub or R2Hub) so the backend stores only ciphertext for the event log; the local SQLite keeps plaintext PayloadJSON, and the existing Ed25519 signature and content/prev-hash verification run unchanged on the decrypted events (the carrier preserves ID/DeviceID/Seq/HLC/DeviceSig, and decryption restores Type/PayloadJSON/ContentHash/PrevEventHash before ApplyEvents). Blob operations pass through unchanged — blobs are already age-encrypted by the bundle layer, so the blob plane is already ciphertext.

Grant events (device.key.granted) ride the hub as PLAINTEXT on both Push and Pull because their payload is itself age-wrapped (the hub cannot decrypt the WCK without the recipient's private key). On Pull, grants are ingested into the keyring in HLC order before the rest of the batch is decrypted, so a newly-approved device obtains its WCKs before decrypting history. If Verify is set, Pull verifies each grant's carrier event before ingesting its WCK so an untrusted hub cannot inject attacker-known workspace keys.

func (h EncryptedHub) CompactEventsBelow(ctx context.Context, floors Cursor) (int, error)

func (h EncryptedHub) DeleteAck(ctx context.Context, deviceID string) error

func (h EncryptedHub) DeleteBlob(ctx context.Context, sha256Hex string) error

func (h EncryptedHub) DeleteDeviceStream(ctx context.Context, deviceID string) (int, error)

func (h EncryptedHub) DeleteSnapshotObject(ctx context.Context, sha256Hex string) error

func (h EncryptedHub) DeleteSweepLock(ctx context.Context) error

func (h EncryptedHub) GetBlob(ctx context.Context, sha256Hex string) (io.ReadCloser, error)

func (h EncryptedHub) GetRetention(ctx context.Context) ([]byte, string, error)

func (h EncryptedHub) GetSnapshotObject(ctx context.Context, sha256Hex string) ([]byte, error)

func (h EncryptedHub) GetSweepLock(ctx context.Context) ([]byte, time.Time, error)

func (h EncryptedHub) ListAcks(ctx context.Context) (map[string][]byte, error)

func (h EncryptedHub) ListBlobs(ctx context.Context) ([]BlobInfo, error)

func (h EncryptedHub) ListSnapshotObjects(ctx context.Context) ([]BlobInfo, error)

func (h EncryptedHub) MigrateLegacyEvents(ctx context.Context, dryRun bool) (int, int, error)

func (h EncryptedHub) Pull(ctx context.Context, after Cursor) ([]state.Event, error)

func (h EncryptedHub) Push(ctx context.Context, events []state.Event) error

func (h EncryptedHub) PutAck(ctx context.Context, deviceID string, raw []byte) error

func (h EncryptedHub) PutBlob(ctx context.Context, sha256Hex string, r io.Reader) error

func (h EncryptedHub) PutRetention(ctx context.Context, raw []byte, ifMatchETag string) error

func (h EncryptedHub) PutSnapshotObject(ctx context.Context, sha256Hex string, body []byte) error

func (h EncryptedHub) PutSweepLock(ctx context.Context, raw []byte) error

func (h EncryptedHub) StatBlob(ctx context.Context, sha256Hex string) (BlobInfo, error)

func (h EncryptedHub) TryDecrypt(ctx context.Context, event state.Event) (state.Event, error)

type FileHub ¶

type FileHub struct {
	Path string
	// RetentionSeqs is the hub's per-device retention horizon (P5-HUB-03,
	// re-based on the Seq transport cursor): for each origin device, the
	// minimum Seq still retained. A Pull whose cursor would leave a gap below
	// a device's floor (after[dev]+1 < RetentionSeqs[dev]) returns
	// ErrSnapshotRequired. Empty means "no compaction yet" (everything
	// retained). Test-only plumbing until snapshot exchange lands
	// (P4-SYNC-02/P4-HUB-11).
	RetentionSeqs map[string]int64
}

FileHub is a file-backed test Hub (HUB-01). The event log is a single JSON array file; blobs are stored in a sibling directory keyed by sha256 hex. It is retained ONLY for tests and the --hub-file spike; the production backend is the R2/S3 implementation (HUB-02).

func (h FileHub) CompactEventsBelow(ctx context.Context, floors Cursor) (int, error)

func (h FileHub) DeleteAck(_ context.Context, deviceID string) error

func (h FileHub) DeleteBlob(_ context.Context, sha256Hex string) error

func (h FileHub) DeleteDeviceStream(_ context.Context, deviceID string) (int, error)

func (h FileHub) DeleteSnapshotObject(_ context.Context, sha256Hex string) error

func (h FileHub) DeleteSweepLock(_ context.Context) error

func (h FileHub) GetBlob(_ context.Context, sha256Hex string) (io.ReadCloser, error)

func (h FileHub) GetRetention(_ context.Context) ([]byte, string, error)

func (h FileHub) GetSnapshotObject(_ context.Context, sha256Hex string) ([]byte, error)

func (h FileHub) GetSweepLock(_ context.Context) ([]byte, time.Time, error)

func (h FileHub) HasEvents(ctx context.Context) (bool, error)

func (h FileHub) ListAcks(_ context.Context) (map[string][]byte, error)

func (h FileHub) ListBlobs(_ context.Context) ([]BlobInfo, error)

func (h FileHub) ListSnapshotObjects(_ context.Context) ([]BlobInfo, error)

func (h FileHub) MigrateLegacyEvents(_ context.Context, _ bool) (int, int, error)

func (h FileHub) Pull(ctx context.Context, after Cursor) ([]state.Event, error)

func (h FileHub) Push(ctx context.Context, events []state.Event) error

func (h FileHub) PutAck(_ context.Context, deviceID string, raw []byte) error

func (h FileHub) PutBlob(ctx context.Context, sha256Hex string, r io.Reader) error

func (h FileHub) PutRetention(_ context.Context, raw []byte, ifMatchETag string) error

func (h FileHub) PutSnapshotObject(_ context.Context, sha256Hex string, body []byte) error

func (h FileHub) PutSweepLock(_ context.Context, raw []byte) error

func (h FileHub) StatBlob(_ context.Context, sha256Hex string) (BlobInfo, error)

type HLC ¶

type HLC struct {
	Last    int64
	Now     func() time.Time
	MaxSkew time.Duration
	// contains filtered or unexported fields
}

func (h *HLC) Receive(remote int64) (int64, error)

func (h *HLC) Send() int64

type Hub ¶

type Hub interface {
	Push(ctx context.Context, events []state.Event) error
	Pull(ctx context.Context, after Cursor) ([]state.Event, error)
	PutBlob(ctx context.Context, sha256Hex string, r io.Reader) error
	GetBlob(ctx context.Context, sha256Hex string) (io.ReadCloser, error)
	DeleteBlob(ctx context.Context, sha256Hex string) error
	// ListBlobs returns metadata for every blob currently on the hub
	// (P5-HUB-02). It is the enumeration primitive for mark-and-sweep hub GC:
	// list everything, delete what no current binding/snapshot references.
	ListBlobs(ctx context.Context) ([]BlobInfo, error)
	// StatBlob returns one blob's current metadata (P4-HUB-12). It is the
	// pre-delete revalidation primitive for hub GC: the LastModified in a
	// ListBlobs snapshot goes stale the instant a concurrent sync dedup-re-puts
	// (and refreshes) the object, so gc re-stats each candidate immediately
	// before deleting it and keeps a blob whose fresh mtime shows it was just
	// re-referenced. A missing blob returns an error wrapping os.ErrNotExist.
	StatBlob(ctx context.Context, sha256Hex string) (BlobInfo, error)
	GetRetention(ctx context.Context) (raw []byte, etag string, err error)
	PutRetention(ctx context.Context, raw []byte, ifMatchETag string) error
	PutSnapshotObject(ctx context.Context, sha256Hex string, body []byte) error
	GetSnapshotObject(ctx context.Context, sha256Hex string) ([]byte, error)
	ListSnapshotObjects(ctx context.Context) ([]BlobInfo, error)
	DeleteSnapshotObject(ctx context.Context, sha256Hex string) error
	CompactEventsBelow(ctx context.Context, floors Cursor) (deleted int, err error)
	PutAck(ctx context.Context, deviceID string, raw []byte) error
	ListAcks(ctx context.Context) (map[string][]byte, error)
	DeleteAck(ctx context.Context, deviceID string) error
	DeleteDeviceStream(ctx context.Context, deviceID string) (deleted int, err error)
	MigrateLegacyEvents(ctx context.Context, dryRun bool) (migrated, kept int, err error)
	GetSweepLock(ctx context.Context) (raw []byte, lastModified time.Time, err error)
	PutSweepLock(ctx context.Context, raw []byte) error
	DeleteSweepLock(ctx context.Context) error
}

Hub is the two-plane zero-knowledge sync backend (HUB-01): (a) the signed HLC-ordered namespace-map event log and (b) the content-addressed encrypted blob store. The hub sees only ciphertext plus a signed carrier map. When wrapped by EncryptedHub (P4-SEC-02/SEC-07), event-log payloads are envelope-encrypted (XChaCha20-Poly1305 under a per-epoch Workspace Content Key) so the hub never stores plaintext Type/PayloadJSON/ContentHash; the carrier (ID/DeviceID/Seq/HLC/DeviceSig) remains plaintext so hub ordering, dedup, and Ed25519 signature verification are unchanged. Implementations must be safe for concurrent use.

Event plane:

• Push appends locally-originated events. Duplicate event IDs are ignored (idempotent), so re-pushing already-delivered events is safe.
• Pull returns, for EVERY origin device present on the hub (device discovery is the hub's job, so a brand-new device's stream is picked up with no cursor entry), every event with Seq > after[DeviceID], in deterministic apply order (HLC, device_id, id). The per-device Seq boundary is exact — Seq is unique per device — so the old inclusive-HLC boundary re-delivery (HUB-13) is retired; no boundary overlap exists. Events with Seq <= 0 (pre-sequence legacy objects) are always returned: they cannot be cursored and rely on event-ID dedup. If any device's cursor has fallen behind the hub's retention horizon (after[dev]+1 < minRetainedSeq[dev]), Pull returns ErrSnapshotRequired so the caller performs a full-state snapshot exchange before resuming incremental pulls.

Blob plane:

• PutBlob stores a content-addressed encrypted blob keyed by its sha256 hex digest. Writes are idempotent: a blob already present is a no-op EXCEPT that the dedup hit refreshes the object's LastModified (an unconditional same-bytes re-put on R2, an mtime bump on FileHub). Content addressing makes the re-write byte-safe, and the refresh is load-bearing: `hub gc` keeps blobs younger than its grace window, so a blob re-referenced by a late recovery sync must look freshly written or the sweep would delete a live blob (P4-HUB-12 / the P6-HUB-01 grace-window residual). Its partner on the read side is StatBlob: gc re-stats each candidate immediately before deleting, so a refresh that lands AFTER gc's ListBlobs snapshot is still honored and the just-re-referenced blob survives.
• GetBlob returns the blob as a stream the caller must close. A missing blob returns an error wrapping os.ErrNotExist.
• DeleteBlob removes a content-addressed blob. It is the reclamation primitive that makes blob/event GC possible (HUB-12) and lets device revoke delete superseded ciphertext so a revoked key can no longer fetch it (SEC-01). A missing blob is not an error (idempotent delete).

The object-key contract is immutable: events and blobs are addressed by content-derived, collision-resistant identifiers and are never overwritten in place (HUB-06). The single exception is the retention manifest, which is a mutable head object guarded by compare-and-swap (PutRetention).

Retention/snapshot plane (P4-SYNC-02 / P4-HUB-11 / P6-HUB-04):

• GetRetention returns the raw signed retention-manifest bytes plus an opaque etag for CAS. Absent manifest (no compaction ever) returns ErrRetentionNotFound.
• PutRetention writes the manifest conditionally: ifMatchETag "" means create-only (the manifest must not exist yet); otherwise the write succeeds only if the current object still matches the etag. A lost race returns ErrRetentionConflict. The hub cannot verify the signature — the manifest is verified fail-closed by importers (see snapshot.go).
• Snapshot objects are content-addressed by the sha256 of their sealed bytes (concurrent compactors can never clobber each other) and immutable; DeleteSnapshotObject exists only so compaction can prune superseded snapshots.
• CompactEventsBelow deletes event objects strictly below each device's floor (Seq < floors[dev]). Callers must have durably published a superseding snapshot + manifest FIRST — the hub does not enforce the ordering; the compactor's confirm-before-delete protocol does.

Ack plane (P4-SYNC-06):

• PutAck writes one device's signed sync-ack marker at meta/acks/<device_id>.json. It is single-writer-per-key (only the owning device writes its own ack) and last-writer-wins (unconditional overwrite).
• ListAcks returns every ack currently on the hub keyed by device id.
• DeleteAck removes one device's ack (idempotent) — used on device revoke.
• DeleteDeviceStream removes an entire origin device's event-log prefix (idempotent), reclaiming a revoked device's stream after a compaction has folded its state into the snapshot. It returns the object count deleted.

Maintenance plane (P4-HUB-12):

• MigrateLegacyEvents re-keys the retired HLC-keyed legacy layout into the per-device seq layout and deletes the migrated legacy objects. It is idempotent, resumable, and FAILS OPEN: an object whose key does not parse or whose body does not decode as a state.Event with matching (device, seq) is reported and KEPT (never deleted), mirroring the dual-read's fail-open posture — a parse bug must never delete an event it cannot account for. Each object is verified by read-back on the new key before the legacy object is deleted. FileHub has no legacy layout and returns (0, 0, nil).
• GetSweepLock / PutSweepLock / DeleteSweepLock are the raw sweep-lock ops the advisory sweep mutex is built on (see SweepLock): a create-only PutSweepLock (returns ErrSweepLockHeld on conflict), a GetSweepLock that returns the lock bytes plus the object's backend LastModified for TTL judgment (ErrSweepLockNotFound when absent), and an idempotent DeleteSweepLock to release or break it. The lock is ADVISORY: it serializes cooperating clients only, not a hostile writer (spec/15).

type Mutation ¶

type Mutation struct {
	Kind      MutationKind
	Upsert    state.UpsertProjectParams // Kind == MutationUpsert
	Tombstone TombstoneMutation         // Kind == MutationTombstone
}

Mutation is one namespace-map effect expressed as plain data. The impure persistence step maps MutationUpsert -> tx.UpsertProject and MutationTombstone -> tx.TombstoneProject; the pure Projection.Apply folds them in memory.

type MutationKind ¶

type MutationKind int

MutationKind enumerates the namespace-map effects Decide can request.

const (
	// MutationUpsert activates/updates the row at Upsert.Path with the winner
	// payload and the event's source coordinates.
	MutationUpsert MutationKind = iota
	// MutationTombstone marks the row at Tombstone.Path deleted with a
	// monotonically non-decreasing tombstone HLC.
	MutationTombstone
)

type ProjectPayload ¶

type ProjectPayload struct {
	Path          string `json:"path"`
	Type          string `json:"type"`
	RemoteURL     string `json:"remote_url,omitempty"`
	RemoteKey     string `json:"remote_key,omitempty"`
	DefaultBranch string `json:"default_branch,omitempty"`
}

func ProjectPayloadFromEvent(payloadJSON string) (ProjectPayload, error)

type Projection ¶

type Projection map[string]ProjectionRow

Projection is the namespace map `Decide` reconciles against, keyed by case-folded path_key. In production applyEventTx loads a slice holding just the event's path (0 or 1 entries); the property test maintains the full map and folds `Decide`+`Apply` over event permutations. `Decide` only ever reads the entry for the event's own path, so both usages behave identically.

func (p Projection) Apply(d Decision) (Projection, error)

type ProjectionRow ¶

type ProjectionRow struct {
	NamespaceID         string // stable namespace_entries.id, for conflict attribution
	PathKey             string // case-folded path key
	Path                string // display path
	Type                string
	RemoteURL           string
	RemoteKey           string
	DefaultBranch       string
	Status              string // "active" | "deleted"
	TombstoneHLC        int64  // meaningful only when Status == "deleted"
	SourceEventHLC      int64
	SourceEventDeviceID string
	SourceEventID       string
	DirtyState          string
}

ProjectionRow is the in-memory namespace-entry state `Decide` reads to reconcile a single event. It mirrors the subset of namespace_entries (joined with git_repos / device_project_state) that governs convergence and holds NO database handle. There is at most one row per path_key, whose Status is "active" or "deleted"; a deleted row is canonical (only PathKey/Status/ TombstoneHLC are meaningful — every other field is zero), because a deleted row's sole convergence-relevant input is its tombstone HLC.

type PullStats ¶

type PullStats struct {
	// RawSeen is the count of objects the backend returned for this pull,
	// before decryption, grant ingestion, skipping, or truncation.
	RawSeen int
	// Truncated is the count of raw events deferred because a workspace key
	// grant is not yet held: since P5-SYNC-01 the defer is PER ORIGIN DEVICE —
	// the deferred device's batch tail is dropped (its per-device cursor
	// holds automatically at the last consumed Seq), while other devices'
	// events keep flowing. Truncated sums the dropped per-device tails.
	// Non-zero means this device's view of the log is INCOMPLETE, so
	// consumers deriving a mark set from local state (hub gc, P6-HUB-01) must
	// refuse to sweep.
	Truncated int
	// Skipped is the count of events dropped in the decrypt pass (malformed
	// envelope, retired enc.v1 traffic, anti-downgrade plaintext). Like
	// Truncated, non-zero means the local replica may be missing references
	// other devices still rely on.
	Skipped int
	// Undecryptable is the count of enc.v2 events that failed AEAD
	// authentication on every held candidate key (corruption, forgery, or a
	// hub-side carrier mutation — P6-SYNC-04). These are NOT dropped: the
	// still-encrypted carrier is forwarded in the returned batch so
	// ApplyEvents records a permanent undecryptable quarantine conflict and
	// the cursor advances past it (no silent loss, no wedge).
	Undecryptable int
}

PullStats reports what a single EncryptedHub.Pull observed. Fields are set only when EncryptedHub.Stats is non-nil, and reset at the start of every Pull so a caller always reads the latest cycle.

type RenamePayload ¶

type RenamePayload struct {
	OldPath string `json:"old_path"`
	NewPath string `json:"new_path"`
}

RenamePayload carries a project.renamed event's source and destination paths.

type RetentionManifest ¶

type RetentionManifest struct {
	V           int                  `json:"v"`
	WorkspaceID string               `json:"workspace_id"`
	Floors      map[string]int64     `json:"floors"`
	Snapshot    RetentionSnapshotRef `json:"snapshot"`
	ProducedBy  string               `json:"produced_by"`
	ProducedAt  int64                `json:"produced_at_hlc"`
	PrevSHA256  string               `json:"prev_sha256"`
	Sig         string               `json:"sig"`
}

RetentionManifest is the hub's single signed retention marker (workspaces/<ws>/meta/retention.json, P6-HUB-04): the per-device retention floors plus the snapshot object that covers everything below them. It is written with compare-and-swap so concurrent compactors cannot lose updates, and chained via PrevSHA256 for audit. One manifest with a floor MAP (rather than one marker per device stream) keeps the multi-device floor update atomic.

func ParseRetentionManifest(raw []byte) (RetentionManifest, error)

type RetentionSnapshotRef ¶

type RetentionSnapshotRef struct {
	// Fields are declared in alphabetical json-tag order so the marshaled
	// signature payload is canonical (matches eventSignaturePayloadV2 style).
	Epoch      int64  `json:"epoch"`
	HLC        int64  `json:"hlc"`
	KID        string `json:"kid"`
	ProducedBy string `json:"produced_by"`
	SHA256     string `json:"sha256"`
}

RetentionSnapshotRef names the current snapshot object inside the manifest.

type SamePathConflictInfo ¶

type SamePathConflictInfo struct {
	Path          string
	WinnerKey     string
	WinnerEventID string
	LoserKey      string
	LoserEventID  string
}

SamePathConflictInfo is the exported, parsed view of a same_path_different_remote conflict's details (P5-SYNC-04), so the CLI resolver can recover the competing variants and their origin events.

func ParseSamePathConflictDetails(detailsJSON string) (SamePathConflictInfo, error)

type Snapshot ¶

type Snapshot struct {
	V           int                 `json:"v"`
	WorkspaceID string              `json:"workspace_id"`
	ProducedBy  string              `json:"produced_by"`
	HLC         int64               `json:"hlc"`
	Epoch       int64               `json:"epoch"`
	KID         string              `json:"kid"`
	Floor       Cursor              `json:"floor"`
	Anchors     []ChainAnchor       `json:"anchors,omitempty"`
	Entries     []SnapshotEntry     `json:"entries,omitempty"`
	Tombstones  []SnapshotTombstone `json:"tombstones,omitempty"`
}

Snapshot is the plaintext full-state snapshot document (snapshot.v1): the derived namespace map with source-event coordinates for LWW convergence, surviving tombstones, per-device chain anchors, and the per-device floor the producing compactor is about to publish. Device-local state (conflicts, key_grant_waits, sync_skipped_events) is deliberately excluded, and grant events are NOT embedded — device approval re-grants all held epochs as fresh events, which always land above the floor.

func BuildSnapshot(ctx context.Context, st *state.Store, producedBy string, hlc int64, floors Cursor) (Snapshot, error)

func UnsealSnapshot(obj []byte, wck []byte) (Snapshot, error)

type SnapshotDraft ¶

type SnapshotDraft struct {
	BlobRef             string `json:"blob_ref"`
	ByteSize            int64  `json:"byte_size"`
	FileCount           int64  `json:"file_count"`
	SourceEventHLC      int64  `json:"source_event_hlc"`
	SourceEventDeviceID string `json:"source_event_device_id"`
	SourceEventID       string `json:"source_event_id"`
}

SnapshotDraft is the LATEST draft-bundle pointer for a draft project, so a bootstrapping device can fetch the age-encrypted bundle blob and hub gc's mark set stays complete after the events that carried it are compacted.

type SnapshotEntry ¶

type SnapshotEntry struct {
	Path                  string         `json:"path"`
	PathKey               string         `json:"path_key"`
	Type                  string         `json:"type"`
	DisplayName           string         `json:"display_name,omitempty"`
	MaterializationPolicy string         `json:"materialization_policy,omitempty"`
	Status                string         `json:"status"`
	SourceEventHLC        int64          `json:"source_event_hlc"`
	SourceEventDeviceID   string         `json:"source_event_device_id"`
	SourceEventID         string         `json:"source_event_id"`
	Git                   *SnapshotGit   `json:"git,omitempty"`
	Draft                 *SnapshotDraft `json:"draft,omitempty"`
}

SnapshotEntry is one active namespace-map row with the source-event coordinates (HLC, device, event id) that make import a pure LWW merge.

type SnapshotEnvelopeInfo ¶

type SnapshotEnvelopeInfo struct {
	WorkspaceID string
	ProducedBy  string
	HLC         int64
	Epoch       int64
	KID         string
}

SnapshotEnvelopeInfo is the parsed plaintext carrier of a sealed snapshot object, exposed so the importer can select WCK candidates by (epoch, kid) before attempting to unseal.

func ParseSnapshotEnvelope(obj []byte) (SnapshotEnvelopeInfo, error)

type SnapshotGit ¶

type SnapshotGit struct {
	RemoteURL     string `json:"remote_url"`
	RemoteKey     string `json:"remote_key"`
	DefaultBranch string `json:"default_branch,omitempty"`
	CloneFilter   string `json:"clone_filter,omitempty"`
	SparseConfig  string `json:"sparse_config,omitempty"`
	LFSPolicy     string `json:"lfs_policy,omitempty"`
	ForgeKind     string `json:"forge_kind,omitempty"`
}

SnapshotGit mirrors the git_repos row attached to a namespace entry.

type SnapshotTombstone ¶

type SnapshotTombstone struct {
	PathKey             string `json:"path_key"`
	TombstoneHLC        int64  `json:"tombstone_hlc"`
	SourceEventDeviceID string `json:"source_event_device_id,omitempty"`
	SourceEventID       string `json:"source_event_id,omitempty"`
}

SnapshotTombstone is one surviving deleted entry, kept so a stale add cannot resurrect a deleted path on a bootstrapped device.

type SweepLock ¶

type SweepLock struct {
	HolderDevice  string `json:"holder_device"`
	AcquiredAtHLC int64  `json:"acquired_at_hlc"`
	TTLSeconds    int64  `json:"ttl_seconds"`
	// Nonce is a per-acquire random token (crypto/rand hex). Release deletes the
	// lock object only when its bytes still match the exact body this acquire
	// wrote — so a sweeper that overran its TTL and had its lock stale-broken by
	// a successor cannot then delete the SUCCESSOR's lock (the nonce differs).
	Nonce string `json:"nonce"`
}

SweepLock is the advisory sweep-lock body serialized to meta/sweep.lock (P4-HUB-12). It coordinates the destructive hub passes (`hub gc`, `hub compact`, `hub migrate-events`) among COOPERATING clients so they do not interleave; it is not a defense against a hostile writer, which is out of scope (spec/15). Staleness is judged by the object's backend mtime (R2 ListObjectsV2 / FileHub file mtime), never by AcquiredAtHLC — a hostile or clock-skewed self-report must not extend a lock. AcquiredAtHLC is the fallback age source used only when a backend cannot report an object mtime.

func ParseSweepLock(raw []byte) (SweepLock, error)

func (l SweepLock) AcquiredAt() time.Time

func (l SweepLock) TTL() time.Duration

type TombstoneMutation ¶

type TombstoneMutation struct {
	Path string
	HLC  int64
}

TombstoneMutation carries a delete/rename-away tombstone.

type WorkspaceKeyring ¶

type WorkspaceKeyring interface {
	// PushKey returns the key new outgoing events encrypt under: the active
	// epoch, its kid (KIDForWCK), and the WCK bytes. epoch == 0 with a nil
	// error means this device holds no workspace key yet (a joiner awaiting
	// its grant). When several keys coexist at the active epoch (P6-SEC-02
	// collision coexistence), the fleet key — grant origin — is preferred over
	// a local self-mint so a legacy joiner converges onto the founder's key.
	// Call Prime first.
	PushKey(ctx context.Context) (epoch int64, kid string, wck []byte, err error)
	// Prime loads every held key's WCK into memory so WCK lookups during a
	// Pull are pure and context-free. EncryptedHub.Pull calls Prime before
	// ingesting in-batch grants and decrypting.
	Prime(ctx context.Context) error
	// WCKCandidates returns the candidate WCKs for decrypting an envelope
	// addressed to (epoch, kid), from the in-memory cache. kid != "" selects
	// the exact key (zero or one candidates); kid == "" (a legacy pre-kid
	// envelope) returns every held key at the epoch, which the caller tries in
	// order — the AEAD authenticates, so a wrong candidate just fails. An
	// empty result means no candidate is held (the grant has not arrived).
	// Call Prime (and ingest in-batch grants) first.
	WCKCandidates(epoch int64, kid string) [][]byte
	// IngestGrant unwraps a device.key.grant addressed to the local device and
	// persists the WCK under its (epoch, kid). Grants for other recipients are
	// a no-op. A grant whose carried kid does not match its unwrapped bytes is
	// rejected, and an already-held (epoch, kid) is never overwritten
	// (P6-SEC-01b/c).
	IngestGrant(ctx context.Context, grant DeviceKeyGrant) error
}

WorkspaceKeyring is the key-epoch abstraction the EncryptedHub decorator uses to encrypt outgoing events and decrypt incoming ones (P4-SEC-07). It is defined here so the decorator depends on the interface, not the concrete keyring, keeping keychain/platform/state dependencies out of internal/sync. The concrete implementation lives in internal/workspacekeys.