21 KiB
Architecture Policy
Base Policy Version: 1.3
Last Updated: 2026-11-22
Upstream Source: 593c9b5227/docs/policy/architecture.md
The source above identifies the adopted baseline. Local native-kit architecture decisions below are repository adaptations, not a new upstream policy adoption.
Purpose And Ownership
The adopted policy defines the application's purpose and the architectural constraints contributors must follow. It owns system boundaries, responsibility and dependency rules, established invariants, and explicit non-goals.
Describe concrete package inventory and implementation mechanics in internal documentation. Link to canonical public contracts for exact behavior and to ADRs for decision rationale.
Architectural Approach
Hexagonal architecture is strongly recommended. Keep pure domain logic independent of external integration details and make dependency direction clear. Native kit types are an intentional contract for model execution, configuration composition, and CLI presentation; do not hide them behind a replacement completion API.
Implement separation with proportionate, idiomatic code. Choose interfaces and package layout to serve demonstrated boundaries. Use adapters where they serve an integration need, not merely to rename an adopted library's public types.
Adopted Constraints And Implemented Structure
Architectural constraints govern current and future development. Record implemented structure accurately, proposals and implementation status in the roadmap, and significant decisions and rationale in ADRs. Describe a target structure as implemented when its changes land.
Constraints must reflect deliberately selected requirements and decisions. Do not promote incidental implementation choices into architectural invariants.
Notarius's fixed pipeline, artifact-family boundaries, and deployment-owned cache permissions remain established product decisions. Successor ADRs 0021, 0022, 0023, and 0024 record the native cutover. Earlier accepted bodies remain historical decisions, with status links identifying superseded portions.
System Shape
Notarius is a Go application for configured structured extraction workflows. Source formats, artifact domains, validation, and output encoding remain explicit boundaries.
The application has one fixed pipeline shape:
input -> chunk -> extract -> merge -> normalize -> output
Pipelines are configured compositions of this shape, not arbitrary DAGs or a general workflow language. Every stage remains explicit; chunking, merging, or normalization must not be hidden inside an extractor.
A stage module implements one pipeline stage. An artifact family owns a cohesive domain feature across its stages, codecs, validators, prompts, identity rules, and reference projections. Family ownership does not combine stages.
Input and chunking are pipeline-wide. Each selected artifact lane owns its extract, merge, and normalize stages. Output aggregates the run's domain results. Ordered steps support generated references without changing the fixed shape.
Notarius is contract-first without being abstraction-heavy. Extension points protect demonstrated boundaries; new abstraction is not itself an architectural goal. Agent Policy owns implementation discipline.
Layers And Dependency Direction
The composition root may depend on concrete implementations. Domain-neutral models and framework layers provide reusable contracts and orchestration. Concrete input, pipeline, output, and validation extensions depend inward on those generic layers. Generic layers must not depend on production extensions; extensions must not compose the application or own process behavior.
Semantic reconciliation is a domain-neutral mechanism for fixed candidate preparation, native request construction, proposal decoding, and safe typed application. It does not own domain identity, durable IDs, warning semantics, or artifact construction rules. Native execution uses the shared producer path.
The root assets package remains a content-only dependency leaf. It may expose
a read-only embedded filesystem but contains no business logic or dependencies
on internal packages or PromptKit. Native source assembly retains its filesystem
context; the package is not a behavioral registry or public extension contract.
This retains ADR-0011's content boundary.
The following dependency boundaries are mandatory:
- extractors and validators do not depend on concrete input adapters;
- provider-specific transport and authentication remain inside PromptKit;
- model-executing framework code, modules, and validators use native PromptKit requests, results, exchanges, errors, and observations directly;
- pure domain types, codecs, reference resolution, and deterministic helpers do not acquire PromptKit dependencies merely because surrounding producers use it;
- other external dependency types cross internal boundaries only where that dependency is an explicit contract.
Shared helpers support demonstrated common needs without moving source-format or domain knowledge into generic packages. Dependencies require a clear correctness, security, interoperability, or complexity benefit. Internal Overview owns the concrete package inventory.
Source And Domain Boundaries
Input modules translate external formats into generic source documents, units, and references. Format-specific fields, schemas, and validation remain with the input module and its integration contract.
A source reference identifies an ordered range of generic units. Framework code preserves ranges unless a module explicitly owns their transformation. Every source unit carries a validated self-reference to its document and unit ID. Auxiliary references provide context or disambiguation, not source evidence; they must not be converted into source references.
Modules own domain semantics, prompt selection, interpretation, deterministic identity, and supported fallback construction. Physical asset centralization does not transfer semantic ownership. Native prompt declarations own default output contracts and schema selections; PromptKit prepares schemas and performs structural validation and repair. Modules declare small static resource dependencies for preflight, not manifests, schema registries, or fingerprints. Intrinsic durable artifact schemas remain application contracts.
Typed artifact registrations declare one stable kind and exact Go type through extraction, merge, normalization, and semantic validation. Resolution requires a compatible codec and matching kind-specific variants. Private framework erasure reports incompatibility as an error rather than a panic.
A kind may provide a typed evidence projection copying direct generic source references. Preparation proves its exact codec-type compatibility. Evidence is reconstructed from serialized normalized artifacts, including supported fallbacks, without generic code inspecting domain JSON or importing domain types. The output boundary owns publication.
When a model selects an entity, modules supply contextual selections and attach opaque application IDs deterministically after exact resolution. Models do not receive or reproduce opaque application IDs. Reconciliation may expose request-local candidate handles, resolved before typed application and never used as durable identity. Retain ADR-0012 and ADR-0013's identity and safety decisions.
Pipeline Composition And Ownership
Configuration and registries select modules, explicit defaults, references, and runtime overrides. Validate selected module and validator options before execution. Preparation constructs the complete implementation set; the runner accepts only that prepared set. Construction failures precede source parsing.
Stage ownership remains explicit:
- input translates external material into the generic source model;
- chunk produces source-addressed plans;
- extract produces artifacts from chunks;
- merge combines extraction outputs;
- normalize reconciles merged output;
- output encodes domain results and enabled auxiliaries into logical files.
The framework materializes plans into chunks before candidate assessment and lane execution. LLM plans use the accepted-result cache; hits rematerialize against the current source without new semantic assessment. Source identity alone does not select a canonical partition. Deterministic chunkers execute normally.
The framework owns orchestration, origin enrichment, aggregation, and handoff provenance. Modules return logical results and classified diagnostics, not CLI reports, physical roots, durable placement, or capture lifecycle.
After pipeline-wide chunking, one pool bounds ready extraction and ready merge/normalize lane-completion jobs together. Extraction dispatch uses stable chunk-first, lane-second order. A continuation becomes ready after its lane's extraction finishes; a worker does not wait for prerequisites while holding a slot. Validation and correction run inside the current job without another worker acquisition. Ordered steps retain their barriers. Do not create unbounded goroutines per lane or chunk.
Completion timing does not choose public ordering or terminal errors. The coordinator orders artifacts, grouped diagnostics, and errors by stable scope. Cancellation stops dispatch, drains started work, and releases workers and native admission before returning.
Warnings are process signals: configuration degradation, qualified fallback, or incomplete configured work. Quality and grounding findings are advisories; accepted cleanup is observation. Modules own classification, while the framework adds origin and aggregates bounded groups. A non-degraded successful run has no actionable warnings. Retain ADR-0015's classification decision, not its retired durable reporting contracts.
Validation And Disposition
Validation is a framework-managed boundary around chunk, extract, merge, and normalize candidates. Validators receive immutable views and return approve, reject, fail, or unavailable findings. Typed validators receive domain values; chunk validators receive generic chunks; serialized validators receive bytes and schema metadata. Incompatible targets or kinds cannot substitute for one another.
Assess each usable initial or revised candidate once through every applicable validator in configured order. Rejections do not short-circuit later validators. Earlier approvals and unchanged revisions do not excuse reassessment; the final allowed response also receives the whole chain. Cancellation or fatal framework failures can interrupt assessment. There is no duplicate final assessment.
Actionable correction guidance is distinct from reason codes, operator messages, and failures. The detecting validator or module owns it. The pipeline aggregates it in order; a native module template supplies the correction assignment. Missing required guidance is a contract failure, not an invitation to invent instructions. Unavailable assessment is not a semantic defect or ordinary acceptance.
The producer's resolved mode owns terminal disposition. Strict requires acceptance; explicitly selected permissive mode may construct a supported fallback. A fallback must satisfy intrinsic shape and downstream invariants but does not rerun the ordinary validator chain or claim semantic approval. Unsupported or invalid fallback construction fails normally. Caller cancellation never initiates fallback. Exact mode and turn controls belong in Configuration.
Default validator chains remain central production composition policy. Configuration can replace a stage-local default, including with an explicit empty chain. Configured order is authoritative. Intrinsic codec validation, source parsing, plan materialization, and necessary module/fallback/cache construction checks remain. Ordinary artifact citation existence/containment checks depend on the configured chain; see validator configuration.
Native Execution Boundary
The composition root constructs one shared native PromptKit engine from the application's ConfigKit result. All model roles use that engine. PromptKit owns transport, authentication, transient retries, structural validation and repair, conversation history, turn iteration, and backend admission. Notarius does not pin omitted native budgets or add outer retries to extend them. Deterministic operations have no generic retry budget or synthetic model request.
One small typed producer helper connects module-owned fixed inputs, native request builders, interpretation, and supported fallback functions with the pipeline assessor. Initial/correction pairs use complete replacement responses and the same declared schema. Enduring principles belong in initial system context; correction supplies current findings and a new assignment. Native coordination carries the growing exchange without manual response replay or regeneration of original references. Normalization applies each proposal afresh to fixed originals, without cross-turn unions.
Check native errors and validation status before interpretation, including failed validation with nil Go error. Native success, stopped, or exhausted status alone does not establish domain acceptance. Do not recover an earlier candidate after a result-less continuation failure or assess an undelivered response. LLM validators execute once per assessment, without a separate semantic correction loop. Calls respect cancellation and applicable native timeouts.
Worker limits and native backend admission are independent. Profiles selecting one backend ID share its engine capacity; different IDs do not imply an endpoint limit. Notarius injects no backend concurrency/queue defaults and has no cross-backend scheduler, second admission queue, or capacity retry loop. Completed turns release admission before assessment so nested validators can use the same limited backend. Native failures retain their causes and follow the producer's mode; they do not become correction guidance.
Configuration And Provenance
ConfigKit owns loading, imports, composition, overlays, inheritance, source
contexts, provenance, and secret-aware inspection. Notarius owns application
meaning through supported definition rules and domain resolution, retaining
ADR-0020.
NOTARIUS_CONFIG is discovery only; field-level environment overlays are not
application configuration. Named pipelines keep structural composition explicit.
One application-owned result supplies engine construction and whole-app/focused inspection. Preserve source contexts and captured selection evidence rather than reparsing settings or maintaining duplicate loaders. Request overrides retain native supplied-value semantics. CommandKit, ckconfig, and ckprompt own standard commands, parsing, presentation, and delivery outcomes. Notarius supplies domain commands and report content, not a universal result envelope.
Offline preflight shares domain resolution and checks statically known module, reference, initial/correction/validator prompt, and applicable profile dependencies before execution. It requires no transcript, reference bytes, credentials, provider call, or run storage. Dynamic selections remain runtime checks. Shared loaders allocate no run storage; capture belongs to the run path.
Trust Boundaries And Threat Scope
Source material and model responses cross application validation boundaries. Host access policy belongs to deployments. Hypothetical privileged actors concurrently modifying the filesystem do not justify new application defenses without an explicit decision. This does not remove adopted correctness boundaries or claim excluded scenarios cannot occur. Raise new threats or guarantees under Agent Policy.
Configuration, operations, and internal documents own credential supply, runtime handling, and mechanisms under Documentation Policy.
State, Output, And Safety
Output, cache, and debug retain independent roots and lifecycles:
- output is durable domain data; modules encode logical files and the CLI places them;
- cache is reconstructible accepted-artifact and LLM-plan state;
- debug is explicitly requested run/operation evidence, not a consumer API.
Cache identity is the opaque native initial prepared message-content hash. Add no configuration, schema, model, session, implementation, or dependency dimensions. Store only final accepted codec artifacts or materialized/assessed plans, not responses, exchanges, proposals, provenance envelopes, or historical usage. Hits perform ordinary decoding/source-usability checks without new semantic assessment. Policy/settings changes may still hit; explicit bypass/refresh controls re-execution. Deterministic work is not cached through manufactured requests.
Fallback and affected dependent work skip lookup and storage; unaffected accepted predecessors remain reusable. Refresh replaces an entry only after new acceptance. Failure preserves an old entry. Cache I/O is best effort and cannot fail otherwise successful work. Legacy caches remain unread and unmodified, with no checkpoint resume, canonical source-only plan store, or automatic migration.
Deployments own cache access policy. Writers request conventional maximum modes and let umask, setgid inheritance, and default ACLs select effective access. Retain confined paths, symlink rejection, atomic publication, validation, and recovery without chmod/chown/chgrp convergence or cache migration. ADR-0017's boundary now applies to the unified cache; output and debug retain separate contracts.
Preserve intrinsic domain payload schemas and logical paths, including supported fallbacks. Consumers need no index, manifest, persisted receipt, or reporting sidecar. Publish artifacts and finish capture before a native completion report. Disclose fallback use independently of diagnostic verbosity. Delivery failure may leave partial stdout and valid published artifacts; retain those artifacts, useful locations, and distinct operation/delivery causes without model retries. Exact report fields and outcomes belong in CLI Reference.
One native execution group records actual initial, continuation, and nested validator executions once. Preserve identity, terminal coverage, and unknown-versus-zero usage without synthetic IDs, copied totals, or historical execution claims on cache hits.
Debug is never a cache input. Capture requires explicit enablement and a nonempty
effective destination; directory configuration alone does not enable it. Requested
capture is required work: allocate before engine construction/preflight, record
incrementally, and finalize once before successful reporting. Capture failures
fail the invocation while retaining available evidence and primary causes.
Update the relative latest link at session start, never completion.
Debug reuses prepared details and native evidence without another preparation/ model call or parallel conversation ledger. Representations are private diagnostics, not stable serialization contracts or exhaustive provider transcripts. Use ConfigKit secret-aware inspection and preserve native credential omissions. Do not directly serialize marked secrets, unrelated environment, or unselected filesystem content. Do not heuristically scan or rewrite source, prompts, responses, or arbitrary application text. Selected evidence may contain full source/reference data, responses, and exchanges; it is not a sanitized bundle. Operators own access and retention as for other application data.
Writes are atomic where practical. Write, move, overwrite, and deletion targets must be narrow and explicit. Never automatically delete output or requested debug bundles. Cache cleanup remains explicit and recoverable. Operations owns physical layout, provisioning, retention, and recovery guidance.
Platform And Distribution
Linux is the supported deployment platform. macOS is supported only as a best-effort development and compilation environment, while Windows is unsupported. Notarius distributes source releases only: an immutable source tag and its checked-in release note identify a release. The project does not publish executable binaries, archives, installers, container images, checksums, signatures, or package-manager entries. Release Policy owns publication requirements and completion; maintainer commands and guards belong to Source Releases.
Architectural Non-Goals
Notarius does not aim to provide:
- an arbitrary workflow graph or general workflow language;
- source-format or extraction-domain behavior in generic framework packages;
- provider-specific transport contracts exposed to modules;
- structural pipeline composition through ad hoc CLI flags;
- implicit cross-stage behavior that bypasses the fixed pipeline;
- replacement kit APIs, duplicated schedulers, or compatibility parsers;
- a public debug serialization format or mandatory execution ledger;
- abstractions introduced solely for hypothetical future complexity.