A Go framework for durable, observable data workflows powered by Temporal.
Development requires Go 1.27.0 or later. The selected Nuki SDK stack uses the Go 1.27 standard library; the previous Go 1.26 floor is no longer sufficient.
Fathomry focuses on explicit contracts, cohesive infrastructure clients, predictable resource ownership, and durable workflow execution. Reliability, observability, bounded resource use, and measured performance guide development.
The project is in early development. Configuration preparation, resource ownership, controlled calls, technical errors, compatibility assessment and testing support are implemented as private foundations. A bounded internal Viper v1 integration supports explicit local acquisition and a separate preparation proof, not an application-wide loading path. The public failure contract provides capability-classified 32-bit codes, extensible typed composition, native-cause inspection and an explicit definition atlas. Settings provides project-owned typed snapshots, atomic publication, subsection reads and an explicit application default. Internationalization gathers component-owned resources, explains numeric errors in an explicit language and presents errors using settings preferences without rewriting native causes. The public resource holder adds typed instance scopes, fixed/following configuration adoption, generation borrowing and cleanup continuation, independently of Internal mechanisms. The public Adapter operation mechanisms add bounded admission, callback/session ownership, typed results and independent evidence custody, without reusing Internal engines or requiring localization. Public Viper and Nacos configuration Adapters now provide independently usable native capabilities and selected raw sources, with independent strict preparation. Public PostgreSQL and MySQL Adapters add bounded SQL, reusable preparation, transactions and provider-specific evidence. They reuse the public resource/operation owners and support direct or Framework composition; shared database contracts expose budget and attribution data without native engine dependencies. Isolated public service checks include independent effect read-back and unique fixture cleanup, not ORM, migration, HA or production qualification. The public Doris Adapter adds finite/incremental SQL, strict labeled Stream Load and label observations through independent SQL-engine contracts. Source/evidence ownership supports direct and Fixed/Follow routes; deployed qualification remains profile-specific. The public MinIO Adapter adds bounded object operations, owned multipart sessions, incremental version enumeration and restricted presigning. It consumes SDK-independent object-storage contracts and supports direct or explicit Fixed/Follow composition with independent evidence. The public Temporal Adapter preserves the selected native SDK capabilities, retained source/use identity, scoped lazy results and actual Worker join with independent evidence. Its local compatibility SDK replacement must be selected explicitly by independent modules; versioned distribution and service qualification remain separate gates.
The public Kafka Adapter
adds asynchronous production, exact/direct reads, classic group sessions and
explicit checkpoints, with the same direct/Framework ownership paths.
Broker contracts contain shared
budget and attribution data, not a universal native client. Deployed TLS/SASL and
failover qualification remain separate from isolated plaintext service checks.
The CLI foundation retains help,
explicit language/output selection, bounded diagnostics and cleanup ownership.
Framework, control-schema assets, project generation/build inspection and all old
leaf commands were withdrawn in #161.
The official tool now adds offline project creation
through project new, producing a root-entry project with dotenv bootstrap,
layered configuration and project-owned settings. It pins an actual published
Framework API revision and is tested as a fresh independent module without a
source replacement. Generation itself performs no dependency resolution or service initialization.
Replacement workflows, modes and persistence are not implemented.
Public foundations, Adapters and Internal integrations remain available.
The library now adds thin Framework metadata preparation
and typed configuration loading.
Independent projects provide their own settings and validation; explicit local/Viper
or remote/Nacos sessions publish accepted snapshots and optionally observe changes.
The project-aware Go CLI entry
now adds config check for compiled project schemas, using explicit dotenv and
Resource-managed configuration loading.
The template uses this entry without restoring an application host or CLI proxy.
The earlier pre-release Adapter, failure, i18n, Framework, settings and CLI surfaces were withdrawn for redesign; failure/v1, settings/v1 and i18n/v1 are rebuilt, resource/v1 supplies public instance ownership, and adapters/v1 supplies shared operation mechanisms. Configsource Adapters are rebuilt over those public foundations, without a string-Condition compatibility facade. Internal configuration acquisition and preparation improvements remain; removing the public layers does not revert their native protocol, cancellation, authentication or type-admission corrections.
An internal Nacos v2 configuration integration supplies raw reads, bounded invalidation subscriptions and owned protocol sessions. Its explicit compatibility profile has local and isolated single-server verification, not production or multi-node certification. See the Nacos contract.
The internal PostgreSQL profile and separate MySQL profile provide the native pools, SQL and transaction protocols reused by the public Adapters. Real-service acceptance remains separate from protocol-peer tests; no control schema or migration engine is included.
The internal Zap integration provides typed/contextual logging, multi-sink evidence and bounded Linux file rotation, gzip and retention. It does not install an observability exporter/backend.
The internal zerolog integration provides bounded synchronous multi-sink JSON logging, structured context association and local-file rotation/gzip. It is independent of Zap and does not implement a public logger, production telemetry exporter or durable execution ledger.
The internal OpenTelemetry integration provides bounded logs, traces and metrics with explicit OTLP HTTP/protobuf export, context propagation and independent evidence. Separate logging bridges preserve existing local sinks. No Collector, Logstash or observability backend is deployed or certified by the local protocol and TLS tests.
The internal Kafka integration provides bounded franz-go production, Kafka-only transactions, exact record reads, direct consumer cursors, classic cooperative groups and explicit checkpoints, with independent evidence, five core codecs, keyed routing and static TLS/SASL. Its tests and service profile do not certify deployed TLS/SASL, failover or the complete data/reference protocol.
Start with the documentation map for current status and reading paths:
- Architecture by topic: responsibilities, design rationale and cross-package guarantees.
- Internal package reference: each
package's
interface.mdcontract and detailed topics. - Development guides: SDK integration, testing and the canonical documentation-writing policy.
- Read AGENTS.md and the maintainer workflow before changing the repository.
- Use Issues for actionable bugs, features, research proposals, and implementation tasks.
- Use Discussions for questions and exploratory conversations.
- Follow SECURITY.md for sensitive reports.
Maintenance is owner-led with Codex assistance. Only write-capable collaborators can create PRs; public readers can inspect the project and share non-sensitive feedback through Issues or Discussions. See AGENTS.md for session entry points and .agents/README.md for pinned skill provenance.
develop is the integration and default branch before the first release. Every
file change, including initialization, enters it through a topic PR. The only
direct bootstrap push is a signed empty root commit. main is created from that
empty root for the first approved release PR and receives releases only; it then
becomes the default branch.
The working layout is lab/fathomry for the product repository and lab/reference
for requirements, per-issue preparation, discussions, draft designs, and pinned
SDK source. Reference materials are workspace-local and do not arrive with a
Git clone; the product build must not depend on them. Public Issues retain enough
approved scope and sanitized evidence to identify missing handoff material.
Use the repository's fathomry-development skill to continue one confirmed issue,
then prepare one next issue with the owner. Product docs/ holds established
contracts, accepted architecture and maintainer guides; its reference/ section
is not the sibling working-literature workspace. Follow
Writing documentation for placement, interface
contracts, truthful status and validation. The
integration-standard index retains
accepted section identifiers and links to their topic pages.
GNU General Public License v3.0 or later. See LICENSE.