0
0
# policy: policy records, attached policies, tangled-vouch
- a market policy ALWAYS runs, both sides, both lanes (scope + full), every decision. no skip paths (the ssh gateway sign-in runs the scope lane only, by design: `internal/services/sshserver/signin.go`)
- the requester publishes the workflow it runs as a record; the RFP strongRefs it; the bidder runs it next to its own
- caching lives inside the engine run, never across parties; the scope lane's memo serves a stored outcome for the same key (every party is in the key: allow 5 min, deny 30 s, `internal/policyengine/manager.go`)
- index: [README.md](README.md). sequence steps: [S1](README.md#step-s1) (vouches), [S3](README.md#step-s3) (record + RFP), [S4](README.md#step-s4) (bidder runs), [S5](README.md#step-s5) (requester runs)
## Records And Fields
| NSID / field | type | rkey | written by | read by | Go | step |
|---|---|---|---|---|---|---|
| `computer.socialweb.temp.policy.ghalite` | record | TID (putRecord at a TID the requester makes); one per contract, kept in `state.Policy` | requester | bidder (via the RFP strongRef), requester (re-check) | `internal/market/requester/policy.go` `BuildPolicyRecord`, `internal/market/requester/runner.go`, `internal/market/participant/policyrecord.go` | S3 |
| `market.rfp` `policies[]` | array of `com.atproto.repo.strongRef` | - | requester | bidder | `internal/atproto/market/records.go` `BuildRFP`; `internal/market/requester/runner.go` `putRFP` | S3 |
| `computer.socialweb.infra#contract` `policy`, `policyArgs` | strings | - | owner | requester (via the ComputeContract) | `internal/market/requester/runner.go` | S2 |
| `sh.tangled.graph.vouch` | record (outside) | subject DID | operators, users | both policies (trust snapshot) | `internal/policyengine/trust/trust.go` | S1 |
| `computer.socialweb.temp.policy.typescript` | record (not in use; no fields defined) | - | nobody | denied | `internal/policyengine/registry/registry.go` | - |
| `com.publicdomainrelay.temp.market.policies.denoWorker` | record (not in use; no fields defined) | - | nobody | denied | `internal/policyengine/registry/registry.go` | - |
| `computer.socialweb.temp.policy.wasm` | test fixture only | - | - | denied as an unknown type | `internal/policyengine/controller/records.go` | - |
- no policy field on `market.bid`, `market.offering` or `compute.*`. the bidder's own Bid object keeps `spec.policy {attached, verdict}` in kcp only
### `computer.socialweb.temp.policy.ghalite`
| field | value |
|---|---|
| `$type` | `computer.socialweb.temp.policy.ghalite` |
| `name` | the workflow name, e.g. `requester-tangled-vouch` |
| `workflow` | the full YAML text of the bundled workflow (or its name when there is no text) |
| `args` | `map[string]string`, from `policyArgs` |
| `requester` | the requester's market DID |
| `perspective` | `requester` |
| `policies` | `[{name, args?}]` |
| `createdAt` | datetime |
- `PolicyRecordWorkflow` reads `workflow` as a YAML string or an object and denies any other `$type` (`internal/market/participant/policyrecord.go`)
- typescript and denoWorker executors are registered as deny ("the policy engine is gha-lite only")
- OAuth: requester and bidder sets carry create (+ update on requester) for `ghalite` and `typescript`; none for denoWorker ([outside.md](outside.md#oauth-scopes-per-role))
## Infra Contract Fields
- `policy`: the workflow name. resolution: `cmp.Or(contract.Spec.Policy, cfg.PolicyWorkflow, DefaultPolicyWorkflow)`
- `PolicyWorkflowName` (`internal/market/requester/policy.go`) trims and lowercases, then: `""` -> `requester-tangled-vouch`; `only-me`, `only_me` -> `requester-only-me`; `mutuals` -> `requester-mutuals`; `tangled-vouch`, `tangled_vouch` -> `requester-tangled-vouch`; any other name passes through
- the bidder does not normalize: `spec.policy` or `bidder-tangled-vouch` (`internal/market/bidder/policy.go`)
- the name must be a bundled workflow, else the contract fails before the RFP (the `compute.vm` record is already written then: `runner.go`)
- `policyArgs`: a JSON object, parsed to `map[string]string` (`internal/market/participant/policy.go` `ParsePolicyArgs`) and stored in the record's `args`. No run receives them today: see "Not wired" below
## RFP Policy StrongRefs
```mermaid
sequenceDiagram
autonumber
participant R as requester
participant RP as requester repo
participant B as bidder
participant E as policy engine (bidder)
R->>R: policy name from Infra contract / ComputeContract
R->>RP: S3 createRecord policy.ghalite {workflow text, args}
R->>RP: getRecord it back: own repo, cid, name, body == bundled workflow
R->>RP: S3 market.rfp {policies: [strongRef]}
RP-->>B: market.rfp
B->>E: own workflow (bidder-tangled-vouch), scope lane (DIDs only)
B->>RP: getRecord each policies[] ref
B->>E: own workflow + each attached workflow, full lane
E-->>B: allow only if all allow
B->>B: S4 bid or no bid
```
- requester write path: `runner.go` step `creatingRfp`: `BuildPolicyRecord` -> putRecord at a TID -> `attachedPolicy` -> `rfpOptions.Policies` -> `putRFP`
- requester re-check `attachedPolicy` (`internal/market/requester/policy.go`): the record is in the requester's own repo, the cid matches, the name matches the contract, the body equals the bundled workflow byte for byte
- bidder: `EvaluatePolicies` (`internal/market/bidder/policy.go`) runs its own workflow (default `bidder-tangled-vouch`), then each RFP ref via `RepoStore.Resolve` (local getRecord or a foreign resolver), `PolicyRecordWorkflow`, `runs.Request{Workflow, Source: uri}`. first deny wins
- the bidder runs the attached workflow with `perspective=bidder` (`internal/market/bidder/bids.go`)
- a restarted runner reuses `state.Policy`; it does not write a second record
## Lanes And Modes
| lane | input | where |
|---|---|---|
| scope | DIDs, `mode: scope`; the bidder passes no RFP, the requester passes the RFP ref | bidder `bids.go` (bid), `adapters.go` (accept); requester `accept.go` `bidAllowedWithPolicy` (each bid); ssh gateway `signin.go` |
| full | self, subject, counterparty, root requester DIDs, the RFP ref (bidder; the requester also the bid ref), `mode: full` | bidder `bids.go` `fullInput`, `adapters.go`; requester `runner.go` (the winner, a resume), `session.go` |
| side | decision | self | counterparty |
|---|---|---|---|
| bidder | bid on an RFP: scope, then own workflow + every attached policy (full) | the bidder DID | the requester DID |
| bidder | take an accept: scope and full again | the bidder DID | the requester DID |
| requester | each bid: scope | `spec.operatorDID`, else the market DID | the bidder DID |
| requester | the winner, before the accept: full, with the attached record's body | the market DID | the bidder DID |
| ssh gateway | sign-in admission: `bidder-tangled-vouch`, scope | `spec.ssh.operatorDid` (none: nobody is admitted) | the signing-in DID |
- run path: `runs.Client.Run` creates a PolicyWorkflowRun and waits (`internal/policyengine/runs/client.go`, timeout `DefaultTimeout` 2 min unless set); `RunReconciler` (`internal/policyengine/controller/run.go`) seeds the trust snapshot and executes
- missing engine, evaluator or a non-boolean `allow` = deny
### Caching (inside the run)
| cache | key | TTL |
|---|---|---|
| trust snapshot seed | `trust/<counterpartyDid>` | per run |
| record | `rec/<uri>/<cid>` (`internal/policyengine/cache/cache.go`) | - |
| verdict | `policy/<workflow>/<mode>\|<perspective>\|<self>\|<subject>\|<counterparty>\|<root>\|<source>\|<rfp>\|<bid>\|<accept>:<args sha8>` (`runs/client.go`) | 30 s default (`cacheTtlSec`) |
| scope verdict memo | `internal/policyengine/controller/scopememo.go` | allow 5 min, deny 30 s (`manager.go`) |
| identlink walk | `trust.Resolver` | 5 min (capped at the earliest `expiresAt`), 5 s with errors; a failed vouch lookup is not cached |
## Bundled Workflows
- embedded: `internal/policyengine/bundled-actions/embed.go` (`workflows/`, `tangy/`), looked up by `Workflow(name)` and `Lookup(uses)`
- every workflow is a `workflow_dispatch` wrapper with inputs `self-did`, `rfp`, `bid`, `accept`, `policy-args`, `mode`, `counterparty-did`, `perspective`, `subject-did`, `root-requester-did`, `cache-key`; it calls `tangy/policy-<name>@v1` and outputs `allow`, `violations`
| workflow | kind | decides |
|---|---|---|
| `bidder-tangled-vouch` | trust (bidder default) | allow when the counterparty is self, shares a root with self, has self as its root, or when any DID of self + its walk ancestors vouches any DID of the counterparty + its walk ancestors |
| `requester-tangled-vouch` | trust (requester default) | the same function, from the requester side |
| `bidder-mutuals`, `requester-mutuals` | trust | self, the same operator, or vouches both ways: the self side vouches the counterparty (or its operator) and the counterparty side vouches self (or its operator). tangled vouches only; the action's description string still says "follows on Bluesky", which it does not read |
| `bidder-only-me`, `requester-only-me` | trust | the counterparty is self or resolves to self or the operator of self |
| `open` | trust | no restriction. only when named, never prod |
| `bid-payload` | work (requester) | the bid payload NSID is in `allowedPayloadNsids` (default `market.bids.free`) |
| `under-4-cpus` | work (bidder) | the VM asks at most `maxCpus` vCPUs (default 4) |
- the action infers its perspective from the `bidder-` prefix unless the `perspective` input says otherwise
- defaults: `api/v1alpha1/types_computevm.go` `BidderDefaultPolicy`, `RequesterDefaultPolicy`
- the policy logic is the bundled `tangy/policy-<name>/dist/index.js`; its `index.ts` imports a source that is not in this repo
### Not wired
- a contract's `policyArgs` reach no run: the requester's runs client has no args, and the bidder runs every attached workflow with its own `policyArgs` (`internal/services/bidder/wiring.go`)
- the work policies read numbers and arrays (`maxCpus`, `allowedPayloadNsids`, `cacheTtlSec`), and args are `map[string]string`: their defaults always apply
## Tangled-Vouch
- default on both sides everywhere; `open` only if the user sets it
- a vouch is `sh.tangled.graph.vouch` at rkey = the subject DID in the voucher's repo; it counts when it exists and `kind != "denounce"`: [outside.md](outside.md#shtangledgraphvouch)
- both directions are needed for a deal: the bidder side vouches for the requester side and the requester side for the bidder side
```mermaid
flowchart LR
SELF["self"] --> T["self side = self + its walk ancestors"]
CP["counterparty"] --> OPC["counterparty side = counterparty + its walk ancestors (identity.md)"]
T --> Q{"one getRecord per pair, both directions: a self-side DID vouches a counterparty-side DID?"}
OPC --> Q
Q -->|yes| ALLOW["allow"]
OPC -->|"operator(counterparty) is self or operator(self)"| ALLOW
Q -->|no| DENY["deny"]
```
- snapshot: `trust.BuildSnapshot` (`internal/policyengine/trust/trust.go`): vouches between self + its walk ancestors and the counterparty + its walk ancestors (at most 256 pairs, nearest first); the vouches of every self-side DID count as self's
- operator resolution (identlink walk): [identity.md](identity.md#walk)
- who writes vouches: market networks declare operator vouches both ways (`internal/app/marketnetwork/vouches.go`, compose `ApplyOperatorVouch`); people write them from any client. the requester OAuth scope offers vouch write as an optional scope
- requester discovery lists the vouches of its operators (self, `spec.operatorDID`, its walk roots; not intermediate ancestors) to add candidates (`internal/market/requester/discovery.go` `vouchedBy`, a listRecords that skips `denounce` and takes rkeys starting `did:`); the policy, not discovery, decides who is served
Real records: the prod requester `aliceoa.bsky.social` and the bidder operator `bobvmbuilder.bsky.social` vouch each other, so `requester-tangled-vouch` and `bidder-tangled-vouch` both allow (bob's bidders are his agents: their walk reaches him).
```json
{"uri": "at://aliceoa.bsky.social/sh.tangled.graph.vouch/did:plc:ocnuqjlzgohypj3zoznermms",
"value": {"$type": "sh.tangled.graph.vouch", "kind": "vouch", "createdAt": "2026-08-05T01:26:28+03:00"}}
{"uri": "at://bobvmbuilder.bsky.social/sh.tangled.graph.vouch/did:plc:lpfuqerea3deuoyrn7ojser4",
"value": {"$type": "sh.tangled.graph.vouch", "kind": "vouch", "createdAt": "2026-08-05T01:26:51+03:00"}}
```
## See Also
- [README.md](README.md), [identity.md](identity.md), [outside.md](outside.md), [market.md](market.md)
- [../SYSTEM.md](../SYSTEM.md#policies), `docs/ARCHITECTURE.md` (open by heading: policy engine)