Fathomry

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.

Direction

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 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. Framework common composition coordinates public operation/resource shutdown, released-evidence reception and once-bound safe localized logs. Framework configuration loads and watches project-owned application settings and independent business values, preserving last-good data and separating publication from instance adoption. The official CLI supplies offline help, error explanations and translation-resource/coverage queries with shared failure identity, explicit language selection and bounded invocation/cleanup behavior. fathomry new <project> now generates an independent typed configuration project: local or remote acquisition and YAML or TOML. Project Boot declares inputs, settings and the selected Framework provider, without Adapter imports. Framework owns acquisition, Load/Watch, released evidence and source cleanup; input lookup and source selection remain explicit. The generated executable validates configuration and exits; it is not a Worker or a complete application runtime. There is no version command yet.

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.

Documentation

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.md contract and detailed topics.
• Development guides: SDK integration, testing and the canonical documentation-writing policy.

Participate

• 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.

Development workspace

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.

License

GNU General Public License v3.0 or later. See LICENSE.