On this page
Connecting an application is only the beginning of keeping its information useful. Authorization, first import, ongoing changes and deletions are distinct checkpoints. An empty provider response also needs to be distinguished from an authorization failure.
Our connectors turn cloud and local source observations into typed events. The event log keeps their revision history, while derived projections can be rebuilt from that record. The transport changes by provider; the evidence contract stays consistent.
The ZortexHQ/try-indra code implements these sync contracts. Supported sources and permissions vary by operating system and connector.
Several ways into one event log
The Google Drive connector uses provider APIs. Its implementation describes a first snapshot through a file listing, enrichment of files with revisions, comments and permissions, then the provider's change feed for incremental work. The connector also maps deletion observations into events. Pagination and resumable positions matter because a large account cannot be treated as one uninterrupted request.
Apple Notes is a different problem. It is a local macOS application, and the Notes source interface supports listing the identities and modification dates of notes separately from fetching their bodies. The production-facing implementation uses macOS scripting through an osascript source; tests use deterministic source fixtures. The separation lets a routine scan find changed notes without paying the cost of reading every body again.
For sites without a practical API, we have also built zortex-miner, a controlled browser with an owner-authorized signed-in session. It operates on web pages rather than pretending every website offers a stable data API. Browser operations and connector synchronization are separate parts of the codebase; a browser task is not automatically proof that its result was ingested into the vault.
The common ingestion principle is more important than the common transport: a connector must describe what it observed and which authority supplied it.
The synchronization path
API / change feed ---+
|
Local application ---+--> Connector: discover / pull / normalize
| |
Browser-assisted ----+ typed events
|
append-only event log
|
projections / index / coverage
|
next scheduled refresh
Different source transports converge on an event log and rebuildable projections.
In the Apple Notes connector, the operations have distinct responsibilities. Discovery supplies a count or census. Pulling enumerates upstream identities and fetches required fields. Normalization maps source records into ProtoEvents. The connector does not decide which revision wins by keeping its own hidden set of seen objects; the event log owns the revision chain.
This division is useful in recovery. If a projector fails, reconstructing it from retained events is different from asking a provider to redeliver everything. If an upstream API loses a cursor, the connector needs a recovery walk; it must not guess that a missing page means the account is empty.
Fast refreshes need a slow backstop
An incremental cursor is a performance optimization, not a proof of complete knowledge.
The Notes code illustrates why. A normal pass enumerates note identifiers and modification dates, then retrieves bodies for records that appear to have changed. But an edit created offline on another device can arrive carrying an earlier modification date. A simple newer-than-watermark comparison would miss it. The connector therefore also specifies a periodic full-body walk. It handles ties at the watermark rather than assuming every source timestamp is unique.
The same pattern appears in API connectors: a change feed can reduce repeated work, but the engineer still has to specify how it starts, resumes, detects drift and recognizes deletion.
An absence requires particular care. A note in Recently Deleted can be represented as an observed deleted item. A note no longer found in a complete listing is different: the connector knows when it observed the absence, not necessarily when the user deleted the note. If the listing was truncated, the absence is not evidence of deletion. The source interface and connector code preserve that difference.
A failed refresh must not look like an empty account
Our typed result boundary distinguishes a valid empty result from an error. The Notes source explicitly treats a macOS automation permission denial as a permission error, not as a successful zero-note scan.
Coverage reconciliation asks another question: how many items does the source say exist, and how many distinct identities have we accounted for? Neither count alone proves the records are usable, but a mismatch can direct investigation.
This is not just a theoretical failure mode. A September 2026 investigation found several unrelated reasons for missed updates. A scheduler had measured elapsed awake process time rather than the age of the last synchronization. Repeated restarts kept delaying work. Drive runs encountered a mismatch when the vault retained identities the source no longer counted. Chrome history had its own retention behavior. The record separates observed causes from an unresolved guess about two Drive file identities.
The important distinction is between what a log proves happened and what the team suspects caused it. A stale failure message after renewed authorization is not evidence that authorization remains broken.
Batching without changing the contract
Provider latency creates pressure to overlap or combine requests. We documented a Gmail batching change where fetching individual messages involved repeated remote calls.
Batching exposed three shared obligations. The request bytes had to be deterministic across the existing replay mechanism; a new batch endpoint needed its own explicit allowlist entry; and the HTTP response parser had to distinguish outer response headers from nested HTTP-shaped text inside a multipart body. Each item response also needed correlation by its Content-ID, rather than an assumption that responses arrive in request order.
The optimization is worthwhile only if these properties survive. Fewer network requests do not justify silently dropping errors or attributing one record's response to another.
How a connector reports its state
The repositories contain the source adapters, typed error handling, synchronization paths and incident investigations behind the connector behavior. The September refresh incident shows why a connector count alone says little about the freshness of the records.
An OAuth consent screen can require a person, a local OS can deny a permission, and a source may return a truncated page or lost cursor. Each condition has a separate error or recovery path; none should be silently reported as an empty account.
The operational question for each connector remains concrete: which account, which source, which read scope, which last successful refresh, and what evidence shows that expected records were observed? Those fields travel with the record so downstream retrieval can distinguish current evidence from an incomplete or failed refresh.
Visual source: code-generated cover study.
