nomos_flutter 0.65.17

Drive the real Nomos Peer Office from a Flutter app. Apple runs the shared Peer Office in JavaScriptCore over its release-linked native AOT kernel; WASM peers execute the same typed runtime contract w [...]

nomos_flutter

nomos_flutter embeds one resident Nomos Peer Runtime in a Flutter process and binds generated business applications to it. Business reads and writes use local custody. Replica convergence is peer-owned background work.

Public contract

The package deliberately exports only:

• NomosPeerRuntimeHost: the process-local owner of the platform shell, Peer Office connection, application-binding inventory, and teardown.
• NomosReception<T>: a stateless view of one peer-owned application binding.
• NomosApprovedModel and CustodyBreakPolicy: immutable decisions supplied by the product.

There is no public start, stop, sync, follow, retry, session, transport, or workspace-open API. Platform services live in the separate pure-Dart nomos_peer_host capability package. The peer calls those capabilities when needed; supplying them cannot control the peer.

Compose the peer once

Place the host above authentication and navigation so ordinary widget changes cannot end its lifetime:

NomosPeerRuntimeHost(
  cloud: cloud,
  capabilities: productPeerHostCapabilities,
  child: const ProductApp(),
)

The executable composition root is the only application layer that should depend on nomos_flutter. A platform-composition package may depend on nomos_peer_host to implement credential, secure-storage, or law-package capabilities. Presentation packages should depend on their generated business application and their own presentation ports, not on either runtime package.

Bind an application

Once local authentication identifies the principal, declare the desired application binding:

NomosReception<AcmeApplication>(
  cloud: cloud,
  application: 'acme-platform',
  principal: 'user:${user.id}',
  contract: acmeReception,
  approvedModel: NomosApprovedModel(
    lawSha256: approvedLawSha256,
    reason: approvedLawReason,
    domainKeys: const ['home'],
    loadPackage: loadBundledLaw,
  ),
  builder: (context, application) => AcmeHome(application),
)

Reception creates no runtime and owns no session, subscription, retry counter, or teardown. It asks the resident peer for a binding and exhaustively renders preparing, ready, or failed. Unmounting and remounting Reception reuses the same ready binding; only unmounting NomosPeerRuntimeHost ends the peer.

The peer opens retained local custody first. Remote authentication, replica observation, transfer, verification, and admission are background convergence work and are not prerequisites for rendering local application state.

Platform storage

Device signing keys and cached provider proofs have distinct lifecycles and stores:

• iOS and macOS use device-only Keychain items.
• Android uses AES-256-GCM keys in AndroidKeyStore and ciphertext under the app's no-backup directory.
• Web uses IndexedDB.

Legacy file-backed device keys are imported into secure storage, verified, and then removed. Failure is typed; there is no insecure fallback.

Supported platforms

• Android: minimum SDK 26.
• iOS: deployment target 13 or later; Apple Silicon and Intel simulators require iOS 14 or later.
• macOS on Apple Silicon or Intel: deployment target 11 or later. Sandboxed apps need the network-client entitlement.
• Web: no additional app configuration.

Add nomos_flutter through pub.dev as usual. Android Gradle resolves the version-matched native host AAR from Maven Central. Apple builds resolve a versioned, checksummed XCFramework ZIP from the Nomos native distributions GitHub Releases: Swift Package Manager verifies its checksum; CocoaPods verifies the same SHA-256 before linking it. No application-specific package server or manual binary download is needed.

For a macOS app created with Flutter's default 10.15 target, set the Runner deployment target to 11.0 in Xcode and platform :osx, '11.0' in macos/Podfile.

See architecture/receiving_group_lifecycle.md for the receiving-group paper and architecture/replica_lifecycle.md for peer-owned convergence.