@projectpac/flow-objects

Two principals agree on one action over things they own, and the action happens without either of them handing anything to the other.

The negotiation is one phase rather than joint-search's two, because here the terms and the program are the same conversation: which objects each side stakes is what the program acts on. Three files are drafted together -- the terms, and the two sources of the program.

One thing here is unlike any other flow in PAC: before a draft is sent, it is compiled. A program that does not compile is not a proposal. The compiler's verdict feeds the drafting run itself -- one correction turn covers an answer that does not fit the output contract, but a program that compiles to nothing fits the contract perfectly and is still unusable, and only this flow can know that. So the diagnostics are appended to the same run, up to its redraft bound, and it stops there.

What travels is the terms, the sources, and the compiled program: all public between the two parties, all reviewable, all agreed byte for byte. The objects themselves are staked into the box by name, and what comes back goes into the principal's own object daemon through an apply. This flow never holds an object it did not just receive on its principal's behalf.

Nothing here is the host's to do for it. The flow declares its own route to the network adapter, so an envelope addressed to it is dispatched rather than refused. It declares its action intent to the router from an optional scope -- a node with no router still runs it, and one that gains a router later hears from it the moment the service comes up. It advertises itself under kind: "flow" from an optional discovery scope, which is how a peer's router finds someone to propose an action to, and it tries again until the advertisement lands. It keeps its actions and mints through ctx.records, and it runs its own two timers.

| | | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | | routes | POST /actions, GET /actions, GET /inventory, POST /mint, GET /mint | | payloads | action.suggestion, action.agreed (the rounds' wire), action.party, action.session, action.failed (the box drive's), action.declined | | records | actions and mints, kept through ctx.records | | background | advance every 2s and sweep every 30s, each on an interval of the flow's own | | needs | the object daemon, the record store, the pexe toolchain, and a box adapter | | intents | action, declared to the router from an optional scope; it needs a peer | | results | one action per action and one mint per mint, declared to ctx.results from an optional scope: GET /flows/results/results reads them beside every flow's | | speaks | advertises itself under kind: "flow", from an optional discovery scope |

It cannot run against anything the PAC repos ship

It needs an external object daemon (dobjd) for the inventory and for importing what a run produced, and the pexe toolchain to compile. Neither is here, so the default dev lane does not install this flow; its vitest suite (tests/objects.spec.ts) is the way to exercise it, and this repo's justfile carries the DON lane for running it against a built digital-objects-network checkout.

Its box half is also known to diverge from the real box and has only ever run against the non-executing test double: the envelope's schema name, its shape, and the fact that it proposes a locally compiled artifact where the box compiles source in-enclave. A real box refuses it at propose; the cluster is parked until a dobjd exists to develop against.

Running it

pnpm check           # includes tests/objects.spec.ts, against the non-executing doubles
just demo            # headless floor: a directory, two seeded nodes, alike, down
just don-build       # build the DON side once (rust toolchain, anvil, postgres)
MODEL=pi just dev    # the full lane: the box, the devnet, both dobjds and guis
just objects         # the trade, once the daemons are stocked (just objects-mint)

The sibling layout

Cross-repo dependencies are link: paths into checkouts beside this one -- nothing of PAC's is fetched from a registry. Clone the repos this one links (the link: values in the package manifests) into the same parent directory, run pnpm install, and everything resolves from source. The flow's whole-node suite lives in tests/, standing up real nodes from the sibling pac-node. The design repo (pac) is the front door: what PAC is, and how the repos fit together.