[antoinetoussaint-byte]

What we are trying to do

Make every endpoint RPC a runnable, and therefore a tool, with zero per-RPC work. The core half is in codefly-dev/core#843. This PR is the generator half: codefly generate runnables and runnable-bindings.

The change

• generate runnables derives an operation for every served unary method that declares authority.hop.v1.policy. No proto edits are needed.
  • A read is written with "recovery": "RECOVERY_RECOMPUTE", empty lookup_scopes and no lookup.
  • A mutation is written with RECOVERY_RECEIPT, exactly the scopes its policy requires, no lookup scopes (its receipt is read under the invoke scopes by the caller that made the effect) and max_attempts: 1.
  • Every operation.json carries the tool's presentation.
  • Receipt lookups (Lookup<Op>, or another operation's lookup_method) are not derived.
• Bounded names (r87 B1). A derived release name over 50 characters is shortened deterministically to a stable prefix and an 8-digit digest of the whole name. A long method name never fails generation. module-document-store authority/behind-the-hop now generates 110 operations. The refusal header no longer claims the methods carry the operation option.
• The report (r87 M2). Each operation is printed with its origin (option or default) and effect. The methods left plain calls are listed with the reason. When anything was derived by default, the run gives the count, names the mutations, and states the grants rule and the codefly.runnable.v0.exclude opt-out:

  runnables: annotations-connect-annotate  /annotations.v1.AnnotationsService/Annotate  default  MUTATION  <digest>
  runnables: 16 method(s) derived by default from their authority policy, 8 of them mutations: …
  runnables: every operation is a tool, offered only to callers whose grants cover its binding; a method no agent may ever call declares `option (codefly.runnable.v0.exclude) = true;`
  

• A method a default derivation cannot turn into an operation (a stream, any_checked_caller, Any, recursion) is listed as not an operation: … and never fails the command.
• operation.json gains recovery. It is omitted when unstated, and runnable-bindings carries it into the prepared policy.
• Core moves to 0c02ef0f (feat(update): pin an agent version, prereleases included, and report a dev build as one #843 head). The origin each operation reports is core's OperationSpec.Declared, not a second reading of the descriptor. The summary names each method once, even when it is published on several endpoints. composition.ProtobufProcedures(set, *endpoint) follows core generate proto: a template whose outputs sit beside --proto regenerates nothing (0.1.145 reports success) or is refused (0.1.160) #836's signature change.

Tests

• TestGenerateRunnablesDerivesEveryMethodBehindTheHop carries the policy and exclude as unknown option bytes, as on disk. It covers:
  • a read, with recompute and no lookup;
  • a mutation, invoked under [write] only with no lookup;
  • an explicit option, kept;
  • a stream, listed rather than refused;
  • an excluded method, not derived;
  • a 55-character release name, bounded to 50 with its digest.
• The document-store oracle and the saas source-operation tests follow the wire spelling: JSON names, int64 as strings, and every non-required key optional. The saas producer's committed package is held to the derived one modulo that re-spelling: the format must be int64/uint64, and array items are compared too. This holds until module-saas-starter regenerates.
• Results. go test ./cmd/generate/ ./pkg/runnables/ ./cmd/show/... passes. golangci-lint --new-from-rev=5536d731 reports 0 issues.

Proof (obin-ai/module-annotations PR #65 at 3a9fcd6, no proto edits)

• Derived tools. 16 per endpoint, 32 in total:
  • reads: GetAnnotation, GetThread, GetVocabulary, ListAnnotations, ListChanges, ListOnTarget, ListTargetKinds, ReadSelection;
  • mutations: Annotate, InstallVocabulary, Redact, Reply, ResolveThread, Retract, Revise, Select.
• Bindings. runnable-bindings prepared all 32.
• End-to-end call. A robin-style JSON call through the module's stand-in hop gave:
  • Annotate 200;
  • Annotate holding only read: 403 from the hop;
  • ListOnTarget 200.
• Wire check. Both answers were walked key by key against their output contracts and conform (camelCase keys, int64 as strings).

Regeneration (expected drift, r87 M1 / decision 7)

Every module's --check gate goes red on this bump, and that is intended:

• hand-marked operations gain a tool presentation;
• contracts take the wire spelling, so package digests move;
• modules behind the hop gain one operation per served method.

Regenerate per module and per composition environment:

codefly generate contracts <module>
codefly generate runnables <module>
codefly generate runnable-bindings --env <env>

A newly derived operation reaches a person only through grants. Add option (codefly.runnable.v0.exclude) = true; on anything no agent may ever call.

Follow-ups (not in this PR)

• sdk-go:
  • Serve the generic Receipts/Lookup. It must admit a lookup only for the recorded ReceiptIdentity (owner and acting principal), holding the lookup scopes or else the invoke scopes, exactly as core's AdmitReceiptLookup decides.
  • Switch the receipt interceptor to core's derivation, so derived mutations can retry safely.
• module-runtime: pkg/runnable.JSONSchema must learn NUMBER, JSON, format and values, and mint a lookup under the invoke scopes when lookup_scopes is empty.
• robin: the reader changes listed for robin's implementer.

Classification: fix at the owner (core plus the CLI generator). No hack.

🤖 Generated with Claude Code