# bloccs v0.1.1 - Table of Contents

> Typed, supervised dataflow on the BEAM: describe a graph of processing stages as TOML and compile it to a Broadway supervision tree, with schema-checked edges and capability-scoped effects.

## Pages

- [bloccs](readme.md)
- [Changelog](changelog.md)
- [LICENSE](license.md)

- Guides
  - [Core concepts](concepts.md)
  - [Getting started](getting-started.md)
  - [Primitives](primitives.md)
  - [Manifest reference](manifest-reference.md)
  - [Effect adapters](effect-adapters.md)
  - [How bloccs compares](comparison.md)
  - [Architecture](architecture.md)

## Modules

- [Bloccs](Bloccs.md): A typed declarative IR for Agentic Computation Graphs (ACGs) that compiles
to a Broadway supervision tree on the BEAM.
- [Bloccs.Parser.Error](Bloccs.Parser.Error.md): A structured parser error pinned to a file + section.
- [Bloccs.Runtime.Config](Bloccs.Runtime.Config.md): Everything the runtime needs to execute one node, derived from the node's
manifest plus the `{network, node, in_port}` identity the compiler knows.

- [Bloccs.Validator.Issue](Bloccs.Validator.Issue.md): A structured validation diagnostic.

- Manifests &amp; parsing
  - [Bloccs.Parser](Bloccs.Parser.md): Parses `.bloccs` TOML manifests into typed structs.
  - [Bloccs.Schema](Bloccs.Schema.md): Versioned schema registry (`Name@N`).
  - [Bloccs.Manifest.Batch](Bloccs.Manifest.Batch.md): Batch / aggregate config from `[batch]`. Present only on aggregate nodes.
  - [Bloccs.Manifest.Contract](Bloccs.Manifest.Contract.md): The node contract: function refs, retry policy, timeout, idempotency.

  - [Bloccs.Manifest.Doc](Bloccs.Manifest.Doc.md): Human-facing documentation block from `[doc]`: intent + owner.
  - [Bloccs.Manifest.Edge](Bloccs.Manifest.Edge.md): A wire connecting an output port on one node to one or more input ports.

  - [Bloccs.Manifest.Effects](Bloccs.Manifest.Effects.md): Declared effect capabilities.
  - [Bloccs.Manifest.Expose](Bloccs.Manifest.Expose.md): Network-level port exposure — promotes a network to be useable as a
subgraph node. v0.1 does not consume `expose` (subgraph composition is
v0.2) but the parser still captures it so manifests are forward-compatible.

  - [Bloccs.Manifest.Join](Bloccs.Manifest.Join.md): Join / correlation config from `[join]`. Present only on join nodes.
  - [Bloccs.Manifest.Network](Bloccs.Manifest.Network.md): A parsed network manifest. Declares topology: which nodes participate,
how their ports are wired, supervision strategy, deploy concurrency.

  - [Bloccs.Manifest.NetworkNode](Bloccs.Manifest.NetworkNode.md): An instantiated node within a network.
  - [Bloccs.Manifest.Node](Bloccs.Manifest.Node.md): A parsed node manifest (`.bloccs`).
  - [Bloccs.Manifest.Port](Bloccs.Manifest.Port.md): A node port. `schema` is a `"Name@N"` reference; `buffer` is the producer
buffer size for input ports (ignored for output ports).

  - [Bloccs.Manifest.Rate](Bloccs.Manifest.Rate.md): Rate-limit (throttle) config from `[rate]`. Caps how fast a node's producer
delivers messages downstream — `allowed` messages per `interval_ms` — using
Broadway's built-in producer `rate_limiting`.

  - [Bloccs.Manifest.Supervision](Bloccs.Manifest.Supervision.md): Supervision strategy declared at the network level.

- Validation
  - [Bloccs.Node](Bloccs.Node.md): `use Bloccs.Node, manifest: "path/to/node.bloccs"`
  - [Bloccs.Validator](Bloccs.Validator.md): Contract validator for parsed node + network manifests.

- Compilation
  - [Bloccs.Compiler](Bloccs.Compiler.md): Compiles a parsed network manifest into Broadway-based source files written
to `_build/<MIX_ENV>/bloccs_generated/<network>/`.
  - [Bloccs.Compiler.Network](Bloccs.Compiler.Network.md): Emits a Supervisor source file that boots every compiled node pipeline
and registers the edge table with `Bloccs.Router`.

  - [Bloccs.Compiler.Node](Bloccs.Compiler.Node.md): Emits Broadway pipeline source file(s) for a single network node.

- Runtime
  - [Bloccs.Context](Bloccs.Context.md): The per-message context passed to a node's pure-core and effect-shell.
  - [Bloccs.Idempotency](Bloccs.Idempotency.md): > #### Runtime internals {: .info}
>
> Infrastructure called by compiler-generated pipelines — not part of the
> stable user API. You drive this through manifests, not by calling it directly;
> signatures may change between minor versions.
  - [Bloccs.Join](Bloccs.Join.md): > #### Runtime internals {: .info}
>
> Infrastructure called by compiler-generated pipelines — not part of the
> stable user API. You drive this through manifests, not by calling it directly;
> signatures may change between minor versions.
  - [Bloccs.Pipeline](Bloccs.Pipeline.md): Runtime helpers called from compiler-emitted Broadway pipelines.
  - [Bloccs.Producer](Bloccs.Producer.md): A GenStage producer used as the input port of a compiled node.
  - [Bloccs.Retry](Bloccs.Retry.md): > #### Runtime internals {: .info}
>
> Infrastructure called by compiler-generated pipelines — not part of the
> stable user API. You drive this through manifests, not by calling it directly;
> signatures may change between minor versions.
  - [Bloccs.Router](Bloccs.Router.md): > #### Runtime internals {: .info}
>
> Infrastructure called by compiler-generated pipelines — not part of the
> stable user API. You drive this through manifests, not by calling it directly;
> signatures may change between minor versions.
  - [Bloccs.Runtime](Bloccs.Runtime.md): > #### Runtime internals {: .info}
>
> Infrastructure called by compiler-generated pipelines — not part of the
> stable user API. You drive this through manifests, not by calling it directly;
> signatures may change between minor versions.

- Effects
  - [Bloccs.Effects](Bloccs.Effects.md): Declared effect capabilities materialized at runtime.
  - [Bloccs.Effects.Capabilities](Bloccs.Effects.Capabilities.md): Effect capability struct injected into a `Bloccs.Context`.
  - [Bloccs.Effects.DB](Bloccs.Effects.DB.md): DB effect facade + backend behaviour.
  - [Bloccs.Effects.DB.Ecto](Bloccs.Effects.DB.Ecto.md): Real DB backend that writes through an Ecto repo — with **no compile-time
dependency on Ecto**. It performs a schemaless `repo.insert_all(table, [row])`
via a runtime call on the repo module you configure, so the published `bloccs`
package never forces `ecto`/`postgrex` on consumers who don't use the DB axis.
  - [Bloccs.Effects.DB.Mock](Bloccs.Effects.DB.Mock.md): Mock DB backend. Refuses out-of-scope table actions. Records every
successful insert for test introspection via `inserts/0`.
  - [Bloccs.Effects.Denied](Bloccs.Effects.Denied.md)
  - [Bloccs.Effects.HTTP](Bloccs.Effects.HTTP.md): HTTP effect facade + backend behaviour.
  - [Bloccs.Effects.HTTP.Allowlist](Bloccs.Effects.HTTP.Allowlist.md): Shared host/method allowlist enforcement for HTTP backends.
  - [Bloccs.Effects.HTTP.Mock](Bloccs.Effects.HTTP.Mock.md): Mock HTTP backend. Refuses non-allowed hosts. Returns stubbed responses
registered per-node via `stub/3`.
  - [Bloccs.Effects.HTTP.Req](Bloccs.Effects.HTTP.Req.md): Real HTTP backend built on [Req](https://hexdocs.pm/req).
  - [Bloccs.Effects.Random](Bloccs.Effects.Random.md): Random effect facade + backend behaviour. Nodes call
`Bloccs.Effects.Random.int/2` against `ctx.effects.random`.

  - [Bloccs.Effects.Random.System](Bloccs.Effects.Random.System.md): Pseudo / crypto random effect.
  - [Bloccs.Effects.Time](Bloccs.Effects.Time.md): Time effect facade + backend behaviour. Nodes call `Bloccs.Effects.Time.now/1`
against `ctx.effects.time`. Default backend is the real wall clock
(`Time.System`); tests can bind a frozen-clock backend.

  - [Bloccs.Effects.Time.System](Bloccs.Effects.Time.System.md): Wall-clock time effect.

- Observability
  - [Bloccs.Coverage](Bloccs.Coverage.md): Structural coverage over a parsed network.
  - [Bloccs.Telemetry](Bloccs.Telemetry.md): Telemetry events emitted by the bloccs runtime, and an optional default
logger handler.
  - [Bloccs.Trace](Bloccs.Trace.md): Records an execution trace of a running network by attaching to bloccs
telemetry, and derives structural-coverage obligations from it.

## Mix Tasks

- Mix tasks
  - [mix bloccs.compile](Mix.Tasks.Bloccs.Compile.md):     mix bloccs.compile path/to/network.bloccs [--dest <dir>]
  - [mix bloccs.coverage](Mix.Tasks.Bloccs.Coverage.md):     mix bloccs.coverage <network.bloccs> [--message <json>] [--trace <file>] [--port <name>] [--wait <secs>]
  - [mix bloccs.new](Mix.Tasks.Bloccs.New.md):     mix bloccs.new <name>
  - [mix bloccs.run](Mix.Tasks.Bloccs.Run.md):     mix bloccs.run path/to/network.bloccs [--message <json>] [--port <name>]
  - [mix bloccs.validate](Mix.Tasks.Bloccs.Validate.md):     mix bloccs.validate path/to/manifest.bloccs

