Reading, writing, validating

// By DID + rkey:
const round = await Queries.fetchRound(did, rkey); // PdsRecord<Round.Round>
const jam = await Queries.fetchJam(did, rkey); // PdsRecord<Jam.Jam>

// By AT URI:
const jam2 = await Queries.fetchJamByUri(jamUri);

// Any record type, low-level:
const rec = await Queries.getRecord({ did, collection, rkey });

getRecord returns a PdsRecord<T> = { uri, cid, value }. Parse an AT URI into its parts with Queries.parseAtUri(uri) → { did, collection, rkey }.

const rounds = await Queries.fetchRoundsForJam(jamUri); // PdsRecord<Round.Round>[]

This asks Constellation which at.atjam.round records link to the jam (via .jam.uri), then fetches each round body. Unreadable rounds are dropped.

// Signups: returns BacklinksResponse ({ links, cursor?, total? }).
const signups = await Queries.fetchSignupsForRound(roundUri);
for (const link of signups.links) {
  const signup = await Queries.getRecord({
    ...Queries.parseAtUri(link.uri),
  });
}

// Submissions and invitations: bodies are fetched for you.
const submissions = await Queries.fetchSubmissionsForRound(roundUri); // PdsRecord<Submission.Submission>[]
const invitations = await Queries.fetchInvitationsForRound(roundUri); // PdsRecord<Invitation.Invitation>[]

fetchSignupsForRound returns the raw backlinks (so you can decide whether to fetch each body); fetchSubmissionsForRound and fetchInvitationsForRound fetch and return the record bodies directly.

const feed = await Queries.fetchHomeFeed([organizerDid1, organizerDid2]);
// PdsRecord<Round.Round>[], deduped, sorted by createdAt descending.

There is no global round index — you supply the DIDs. See the read-layer limitation.

const handles = await Queries.resolveHandles([did1, did2]); // HandleMap (Record<string,string>)
// DIDs that fail to resolve are simply absent — fall back to the DID.

const { pds, handle } = await Queries.resolveDid(did);

Required: name, createdAt.

{
  $type: NSIDS.jam,
  name: "Old Salt Song Club",
  // optional: description, kind, links
  createdAt: new Date().toISOString(),
}

Required: jam, assignment, acceptedSubmissionTypes (≥1 NSID), milestones (≥1), createdAt.

{
  $type: NSIDS.round,
  jam: { uri: jamRef.uri, cid: jamRef.cid }, // strong-ref to the jam
  assignment: "Make anything. Submit a Bluesky post as proof.",
  acceptedSubmissionTypes: ["app.bsky.feed.post"],
  milestones: [{ label: "submission-deadline", date: deadlineIso }],
  // optional: name, subject, closingEvent, joinMode, networkGate
  createdAt: new Date().toISOString(),
}

joinMode defaults to "open" when omitted. For "hosted"/"network", see the two-sided flow below.

Required: round, createdAt. For open rounds, that is all.

{
  $type: NSIDS.signup,
  round: { uri: round.uri, cid: round.cid },
  ...(invitation ? { invitation } : {}), // required by readers for hosted/network
  // optional: note
  createdAt: new Date().toISOString(),
}

This is exactly what web/app/components/signup-button.tsx builds.

Required: round, invitee (a DID), createdAt.

{
  $type: NSIDS.invitation,
  round: { uri: round.uri, cid: round.cid },
  invitee, // the DID being invited
  // optional: note
  createdAt: new Date().toISOString(),
}

This is what web/app/components/invite-form.tsx builds.

Required: round, createdAt, and a deliverable — one of two, a gradient rather than a coin-flip:

• payload (preferred) — a strong-ref to a record on another app: content-addressed, verifiable, portable. Its $type SHOULD appear in the round's acceptedSubmissionTypes.
• url (fallback) — a plain link, for work that isn't an ATProto record yet (an itch.io build, a hosted doc). Unverifiable and mutable, so prefer payload.

The Lexicon can't express "exactly one of" across fields, so both are optional in the schema and the "at least one" rule lives in code: read every deliverable through Submission.getDeliverable(submission), which returns the record (preferred), else the url, else null.

// Preferred — a record payload:
{
  $type: NSIDS.submission,
  round: { uri: round.uri, cid: round.cid },
  payload: { uri: payload.uri, cid: payload.cid }, // e.g. an app.bsky.feed.post
  // optional: note
  createdAt: new Date().toISOString(),
}

// Fallback — a plain link, when the work isn't an ATProto record:
{
  $type: NSIDS.submission,
  round: { uri: round.uri, cid: round.cid },
  url: "https://my-itch.io/the-build",
  createdAt: new Date().toISOString(),
}

web/app/components/submit-form.tsx resolves a pasted link to an AT URI, checks its collection is in the round's acceptedSubmissionTypes, then fetches the record to capture its CID before building the payload strong-ref.

In one sentence: a signup counts only if someone allowed to invite actually invited that exact DID to that exact round — and you can't fake who invited you, because the inviter is simply whoever wrote the invitation record. Everything below is that idea, checked condition by condition.

The rules, by joinMode (derived via getJoinMode — unknown values resolve to "open"):

• open → always { valid: true }. No invitation expected.
• hosted / network → the signup must have an invitation strong-ref. Then the referenced invitation is fetched and must satisfy:
  • invitation.invitee equals the signup's creator DID (parsed from the signup's AT URI), and
  • invitation.round.uri equals the round's URI.
  • The inviter DID is parsed from the signup's invitation.uri; the organizer DID is parsed from the round's jam.uri.
• hosted → the inviter must be the organizer.
• network → the organizer is always a valid inviter (the chain root). Otherwise the inviter must have their own valid signup to the round — the validator walks the chain recursively, detecting cycles. When networkGate is "contributed" (derived via getNetworkGate; unknown → "signup"), the inviter must additionally have at least one submission to the round.

The default fetchers go through Queries; tests inject stubs via the fetchers option to drive the matrix deterministically (see lexicons/src/validate.test.ts).