README
¶
Modary
Modary is a Go-first framework for governed modular applications. Consumers define their own modules and typed business Actions; Modary runs every Action through the same authorization, Preview/Execute binding, idempotency, transaction, and audit semantics across CLI, HTTP, MCP, and custom surfaces.
Use Modary when an application needs explicit composition, inspectable module boundaries, durable SQLite transactions, and consistent policy enforcement. Modary does not own product schemas, domain language, UI, deployment, identity provisioning, or release artifacts.
Stability
v0.1.0-alpha.1 is a pre-v1 Alpha contract. Pin the exact version, review the
versioning policy, and read the
known limitations before production use. The F0
durable profile is one process and one SQLite database; it is not a hostile
extension sandbox, distributed transaction system, or public-internet IAM
solution.
Go 1.26 or newer is required. Node.js is not required by framework or example workflows.
Quickstart
Run the public Counter example from the tagged source:
git clone --depth 1 --branch v0.1.0-alpha.1 https://github.com/iiwish/modary.git
cd modary
make bootstrap
cd examples/counter
GOWORK=off go run ./tools/modary verify
GOWORK=off go run ./tools/modary generate --check
GOWORK=off go test ./...
GOWORK=off go run ./cmd/counter-console version
The final command prints:
counter-console 0.1.0
Continue with the complete quickstart to build and preview the governed Counter Action. Then use Create Your First Independent Application to copy the example outside the framework checkout and resolve the exact public Go module version without a local replacement.
Add Modary To An Application
go get github.com/iiwish/modary@v0.1.0-alpha.1
go mod tidy
An application is an ordinary independent Go module. It owns one pure
appkit.Definition, a modary.yaml project manifest, an application command,
a pinned project tool, consumer modules, migrations, generated contracts, and
tests. Module discovery is explicit Go composition, not source scanning or
runtime registration.
Runtime Model
consumer transport / appcmd
|
v
action.Runtime
intent authorization
Preview + plan binding
impact authorization
idempotency reservation
transaction + reauthorization
handler + required audit
Every state-changing business path converges on action.Runtime. Consumers do
not receive raw transaction, lifecycle, registry, or Handler authority from the
assembled application.
Public Packages
| Package | Responsibility |
|---|---|
action |
Typed Action descriptors, schemas, plans, errors, and Runtime |
module |
Definitions, dependency graph, typed capabilities, lifecycle |
appkit |
Pure application composition and opaque assembled facades |
appcmd |
Consumer application commands and server orchestration |
projecttool |
Verify, deterministic generate/check, and build workflows |
transport/httpapi |
Explicit health, Action HTTP, MCP, and static handlers |
adapters/* |
Official SQLite, local Identity, RBAC, and SQL Audit modules |
scope, identity, authz, audit, database |
Narrow framework contracts |
Consumer code imports only public packages. Everything below internal/ is a
framework implementation detail.
Documentation
Start at the documentation index:
- Installation and version pinning
- Framework and consumer ownership
- Add a consumer module
- Expose a governed Action
- Troubleshooting
- Deployment and production checklist
- Complete F0 contract
Framework Verification
Contributors run:
make bootstrap
make acceptance
make ci
These gates cover framework and copied-out consumer tests, vet, race, repetition, fuzz smoke, generated drift, neutrality, source stability, native builds, and Linux, Darwin, and Windows cross-build contracts.
License And Security
Modary is licensed under the Apache License 2.0. Third-party attributions are recorded in NOTICE. Report vulnerabilities through the private channel in SECURITY.md, not a public issue.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package action defines typed governed operations and the Runtime that applies schema validation, authorization, Preview binding, idempotency, transactions, and audit semantics consistently across consumer channels.
|
Package action defines typed governed operations and the Runtime that applies schema validation, authorization, Preview binding, idempotency, transactions, and audit semantics consistently across consumer channels. |
|
Package adapters contains cross-adapter conformance tests for Modary's official SQLite, local Identity, RBAC, and SQL Audit implementations.
|
Package adapters contains cross-adapter conformance tests for Modary's official SQLite, local Identity, RBAC, and SQL Audit implementations. |
|
internal/sqlitetest
Package sqlitetest provides privileged SQLite control for adapter tests.
|
Package sqlitetest provides privileged SQLite control for adapter tests. |
|
localidentity
Package localidentity provides an explicit, SQLite-backed local identity Adapter.
|
Package localidentity provides an explicit, SQLite-backed local identity Adapter. |
|
rbac
Package rbac provides an explicit, durable, default-deny RBAC Adapter.
|
Package rbac provides an explicit, durable, default-deny RBAC Adapter. |
|
sqlaudit
Package sqlaudit provides a neutral SQLite-backed audit Hook.
|
Package sqlaudit provides a neutral SQLite-backed audit Hook. |
|
sqlite
Package sqlite provides Modary's explicit, neutral SQLite durable profile.
|
Package sqlite provides Modary's explicit, neutral SQLite durable profile. |
|
Package appcmd provides consumer-owned application commands without exposing Modary lifecycle or Action handler internals.
|
Package appcmd provides consumer-owned application commands without exposing Modary lifecycle or Action handler internals. |
|
Package appkit assembles a governed Modary application from consumer-owned Module registrations without exposing lifecycle or execution internals.
|
Package appkit assembles a governed Modary application from consumer-owned Module registrations without exposing lifecycle or execution internals. |
|
Package audit defines bounded, channel-independent records for governed Action decisions and the Hook used to persist them.
|
Package audit defines bounded, channel-independent records for governed Action decisions and the Hook used to persist them. |
|
Package authz defines intent and impact authorization contracts for governed Actions without prescribing a policy language or storage implementation.
|
Package authz defines intent and impact authorization contracts for governed Actions without prescribing a policy language or storage implementation. |
|
components
|
|
|
governedpostgres
module
|
|
|
oidc
module
|
|
|
otel
module
|
|
|
postgres
module
|
|
|
Package database defines the narrow SQL value and capability contracts available to consumer Action handlers.
|
Package database defines the narrow SQL value and capability contracts available to consumer Action handlers. |
|
Package identity defines validated actor, session, password-authentication, and bearer-authentication contracts independently from authorization policy.
|
Package identity defines validated actor, session, password-authentication, and bearer-authentication contracts independently from authorization policy. |
|
internal
|
|
|
actionpersistence
Package actionpersistence defines the framework-owned persistence boundary used by the Action runtime and official storage adapters.
|
Package actionpersistence defines the framework-owned persistence boundary used by the Action runtime and official storage adapters. |
|
callbackcontract
Package callbackcontract provides concurrency-safe guards for extension callbacks whose invocation count is part of a framework correctness contract.
|
Package callbackcontract provides concurrency-safe guards for extension callbacks whose invocation count is part of a framework correctness contract. |
|
databasecontrol
Package databasecontrol owns Modary's privileged database assembly boundary.
|
Package databasecontrol owns Modary's privileged database assembly boundary. |
|
filepolicy
Package filepolicy implements operating-system file security checks shared by framework surfaces that retain an opened file descriptor.
|
Package filepolicy implements operating-system file security checks shared by framework surfaces that retain an opened file descriptor. |
|
jsonschema
Package jsonschema owns the framework's offline Draft 7 admission graph, panic-contained compiler, and bounded flag-only validator.
|
Package jsonschema owns the framework's offline Draft 7 admission graph, panic-contained compiler, and bounded flag-only validator. |
|
jsonvalue
Package jsonvalue implements the shared, bounded JSON document boundary used by Action contracts and protocol envelopes.
|
Package jsonvalue implements the shared, bounded JSON document boundary used by Action contracts and protocol envelopes. |
|
moduleassembly
Package moduleassembly owns private service keys used by official durable adapters.
|
Package moduleassembly owns private service keys used by official durable adapters. |
|
quality
Package quality hosts repository-level contract checks that do not belong to one runtime package.
|
Package quality hosts repository-level contract checks that do not belong to one runtime package. |
|
runtimecontrol
Package runtimecontrol owns the privileged Action persistence assembly contract.
|
Package runtimecontrol owns the privileged Action persistence assembly contract. |
|
safeerr
Package safeerr classifies errors received across dependency boundaries without invoking caller-defined Is, As, or Unwrap methods.
|
Package safeerr classifies errors received across dependency boundaries without invoking caller-defined Is, As, or Unwrap methods. |
|
sqlpolicy
Package sqlpolicy provides a small, dialect-neutral SQL lexical boundary.
|
Package sqlpolicy provides a small, dialect-neutral SQL lexical boundary. |
|
testsupport
Package testsupport contains explicitly non-production dependencies used by framework tests.
|
Package testsupport contains explicitly non-production dependencies used by framework tests. |
|
transactionoutcome
Package transactionoutcome carries framework-owned proof of how a transaction callback completed.
|
Package transactionoutcome carries framework-owned proof of how a transaction callback completed. |
|
Package module defines pure Module registrations, dependency verification, typed capability-scoped services, and deterministic application lifecycle.
|
Package module defines pure Module registrations, dependency verification, typed capability-scoped services, and deterministic application lifecycle. |
|
Package projecttool provides pure inspection, deterministic generation, and Node-free builds for a consumer-owned Modary application Definition.
|
Package projecttool provides pure inspection, deterministic generation, and Node-free builds for a consumer-owned Modary application Definition. |
|
Package scope defines validated consumer-owned execution identifiers used to isolate data, authorization, plans, idempotency records, and audit events.
|
Package scope defines validated consumer-owned execution identifiers used to isolate data, authorization, plans, idempotency records, and audit events. |
|
transport
|
|
|
httpapi
Package httpapi provides explicitly mounted HTTP, MCP, health, and static SPA handlers for a Modary application.
|
Package httpapi provides explicitly mounted HTTP, MCP, health, and static SPA handlers for a Modary application. |