At this level
ai.newnal · 1- ai.newnal.illi.account.exchangeCode procedure Exchange the one-time code from a client=native sign-in (delivered to the app at …/native/callback?code=…, 60 s, single use) for a session token, sent afterwards as Authorization: Bearer on every call and on /events. The code is bound to the code_challenge the app sent when it started the sign-in; codeVerifier proves it is the same app (PKCE-style S256), which stops a code obtained for another account from being injected into the app.
- ai.newnal.illi.account.family.signIn procedure Sign a family member in to ILLI from the native family app without the PDN's OAuth sign-in and consent screen: the app presents the member's scoped familyApp app password (which it keeps) and its platform attestation; the Service Agent Node opens the session, joins the account to the service sphere on first use and returns the family session. Used at first connection and at every re-login. Web clients use the OAuth BFF (/oauth/login) instead.
- ai.newnal.illi.account.getAttestationNonce procedure Issue a server nonce (5 minutes) that a client binds into its attestation before calling account.requestPDNCreationGrant, account.parent.signIn, account.family.signIn or device.requestOnboardingCode. The nonce is an attestation session: the attestation bound to it may be presented again for the same client kind and subject until it expires; a failed verification ends the session. Devices put it in the Android key-attestation challenge of a key provisioned through Newnal's RKP; family apps pass i
- ai.newnal.illi.account.getSession query Describe the signed-in ILLI session: the account behind the illi_session cookie, which app it belongs to, and when the account joined the ILLI service. Served by the ILLI Service Agent Node.
- ai.newnal.illi.account.parent.signIn procedure Sign a parent account in to ILLI from the device without the PDN's OAuth sign-in and consent screen: the device presents the parent's scoped deviceApp app password (which it keeps) and its attestation; the Service Agent Node opens the delegated session, joins the account to the service sphere on first use and returns the device-app session. Used at first connection and at every re-login.
- ai.newnal.illi.account.parent.startOAuth procedure Start a parent's OAuth sign-in on the device through the PDN's own page (BFF), for an existing Newnal ID whose credentials are typed on the PDN page. Device-created accounts, and existing ones whose credentials the device app takes itself, sign in with account.parent.signIn instead. client=native ends with a one-time code on the device app's App Link for account.exchangeCode instead of a cookie.
- ai.newnal.illi.account.registerPushToken procedure Register this installation's push token for user-visible notifications only: one token per session, replaced on rotation, removed on logout. Pushes carry generic text and { homeId, kind } only; events travel over SSE.
- ai.newnal.illi.account.requestPDNCreationGrant procedure Issue a 60-second creation grant (a service-auth JWT for the PDN's ai.newnal.pdn.server.createAttestedAccount) to an attested ILLI client. In the PoC a device needs no attestation; in production the manufacturing-key or platform attestation is mandatory.
- ai.newnal.illi.account.unregisterPushToken procedure Remove a push token of the signed-in account.
- ai.newnal.illi.artwork.ackDelivery procedure Device app. Acknowledges one delivery: outcome received after the whole file was downloaded, its CID, size and sha256 matched the manifest and a decoder frame was prepared without starting playback (playbackReady true); outcome failed with the failure stage otherwise. received is final and counts the work's originals as used; a failure consumes nothing. The same requestKey replays the first answer.
- ai.newnal.illi.artwork.defs defs Delivery counts of one occurrence. Delivered means downloaded and acknowledged, not played.
- ai.newnal.illi.artwork.excludeOccurrence procedure Root/main admin cancels an unsent occurrence before the one-hour lock. No automatic substitute.
- ai.newnal.illi.artwork.getArtwork query Family app (active guardians; parents excluded). One work with its versions, sources, occurrences and deliveries. Stored versions can be previewed before delivery (getPreview).
- ai.newnal.illi.artwork.getFamilyWork query Device app. One received work by its delivery: the card and whether its manifest can still be read. Works outside today's recommendations included.
- ai.newnal.illi.artwork.getManifest query Device app. The fixed composition version, CID, size, sha256 and download URL of one delivery. Cancelled or expired unreceived deliveries have no manifest; received versions remain accessible after retry expiry. The file and a new acknowledgement follow the same access rule.
- ai.newnal.illi.artwork.getPreview query Exact stored-version product preview for active guardians, including before delivery.
- ai.newnal.illi.artwork.listArchive query Family app (active guardians; parents excluded). History cards of the home's generated works, newest first, with the stored preview when there is one.
- ai.newnal.illi.artwork.listDeliveries query Device app. Deliveries to download, oldest first: offered or failed deliveries before expiry. state=all also lists received, cancelled and expired deliveries. A delivery whose version can no longer be sent is left out of the open list (its manifest, file and acknowledgement would answer DeliveryWithdrawn). Read on reconnect and on artworkDelivery events; the events are hints, kept 30 days.
- ai.newnal.illi.artwork.listFamilyWorks query Device-local daily recommendation membership/order snapshot. Stored version introductions are reused; a missing sentence may fill on a later read. An explicit snapshotId retains that device's published history across midnight.
- ai.newnal.illi.artwork.listScheduled query Family app (active guardians; parents excluded). The occurrences of a local-date interval (default: today) with their revision, lock time and preview, the four slot outcomes of every planned day in the interval, and changesUntil, the deadline for changing tomorrow's draft.
- ai.newnal.illi.artwork.recordPlayback procedure Device app. Records a playback event of a delivered work: started (clears the unplayed state), paused (with the position the viewer can resume from) and completed. Playback is independent of delivery and is never an acknowledgement. Events are idempotent by eventKey within the delivery; the server keeps the latest paused position.
- ai.newnal.illi.artwork.updateSubtitle procedure Root/main admin accepts a photo-only supplied subtitle render before the one-hour lock. Completion is asynchronous.
- ai.newnal.illi.device.getState query Everything the device needs to render: status, onboarding code while waiting, home, parents, members, pending requests and the acknowledged event cursor.
- ai.newnal.illi.device.link procedure The caller enters the device's onboarding code and becomes the root admin: creates the home and the family sphere on the caller's PDN with parent 1 and the caller as first members.
- ai.newnal.illi.device.reportStatus procedure Device heartbeat (every 60 s): updates lastSeenAt, the online flag and the OS image version (firmwareVersion).
- ai.newnal.illi.device.requestOnboardingCode procedure Register the device (device id, model) under parent 1's device-app session and issue a one-time onboarding code shown on the device.
- ai.newnal.illi.device.unlink procedure Unlink the home's device (root admin). The home keeps its data; the device shows set-up again.
- ai.newnal.illi.deviceApp permission-set
- ai.newnal.illi.deviceAppPrivate permission-set
- ai.newnal.illi.events.ack procedure The device records the last event id it has shown to the parents, so one-shot notices appear exactly once.
- ai.newnal.illi.events.defs defs
- ai.newnal.illi.events.list query Events of a home after a cursor (polling and native catch-up; the SSE stream at GET /events serves the same log).
- ai.newnal.illi.family space Shared data of one ILLI device and the family around it: parent slots, members, photos and videos, and the parents' My Data records.
- ai.newnal.illi.family.artworkVersion record One finished version of a family work: the video the media service made, stored as a blob on the root admin's PDN and referenced from the family sphere (root admin repo, written by the Service Agent Node with the root admin's session). The record key is deterministic, "v1-" plus the first 32 hex characters of sha256 over homeId, artworkKey, mediaArtworkId and compositionVersion joined with newlines, so a retried write replaces the same record with the same content and other content under the sam
- ai.newnal.illi.family.credentialEnvelope record not from the namespace authority A parent's credentials (Newnal ID handle and password, scoped app passwords, parent 1's Private Phone key) sealed by the ILLI device to the root admin's custody public key (crypto_box_seal: ephemeral X25519 + HKDF + AES-256-GCM). Written by the device in the parent's repo; only the root admin can open it. Deleted by the device once a custodyReceipt is seen.
- ai.newnal.illi.family.custodyReceipt record not from the namespace authority Written by the root admin after opening a credentialEnvelope and storing its contents in their Private Sphere; tells the device it may delete the envelope.
- ai.newnal.illi.family.dataEntry record ILLI's provenance note for a My Data record written in a parent's name: who entered it, from which source, and why. Written by the acting admin into their own repo in the family sphere; the My Data record itself stays generic.
- ai.newnal.illi.family.mediaItem record One original photo or video in the home's content bank. The original and its sidecar are blobs on the author's PDN; the thumbnail, display rendition, poster, dimensions and capture time are produced by the media service and uploaded by the Service Agent Node to the same PDN after the item was created, so a freshly created item may carry only the original and its upload-time content hash for exact deduplication.
- ai.newnal.illi.family.member record Human-facing membership of one account in this home (rkey = the member DID), written by the root admin as a portable mirror of the Service Agent Node's role table.
- ai.newnal.illi.family.parentSlot record One of the two parent slots of a home. Written by an admin into the admin's own repo; the Service Agent Node resolves one record per slot by the newest updatedAt.
- ai.newnal.illi.family.phoneIdentity record The author's Private Phone account, identified by its Matrix ID (the server name is part of the MXID). One account per person: a family member's appears in every family sphere the member belongs to, and parent 1's is the account the ILLI device calls with (parent 2 has none). Written by the Service Agent Node after phone.registerIdentity.
- ai.newnal.illi.family.phoneRoom record Registry entry for a Private Phone room of this home, written by the ILLI Service Agent Node with the root admin's session after it created the room through the Messaging Node's Admin API: the home's group room or a direct room between a member and parent 1.
- ai.newnal.illi.familyApp permission-set
- ai.newnal.illi.familyAppPrivate permission-set
- ai.newnal.illi.home.createInvite procedure Create an invite link (root admin). The token is shown once and delivered by hand.
- ai.newnal.illi.home.defs defs
- ai.newnal.illi.home.get query One home: device, parents, members; for the root admin also open invites, limits and sync status.
- ai.newnal.illi.home.join procedure Join a home with an invite token as a member (no approval step).
- ai.newnal.illi.home.leave procedure Leave a home (member or main admin).
- ai.newnal.illi.home.listInvites query Open invites of the home (root admin).
- ai.newnal.pdn.server.createAppPassword procedure not from the namespace authority Create an App Password bound to an OAuth scope. Sessions created from it through com.atproto.server.createSession carry exactly the permissions of that scope, as an OAuth session would. Requires a full-access session.
- ai.newnal.pdn.server.createAttestedAccount procedure not from the namespace authority Create an account on behalf of a client attested by a trusted issuer. Authenticated with a service-auth JWT (iss = trusted issuer DID, aud = this PDN, lxm = this method, exp - iat <= 60 s, unique jti). No invite code, no captcha. Without handle the server generates a memorable one; without email the server stores the placeholder <label>@newnal.id. Returns a full session, like createAccount; clients that need a scoped session create a scoped app password with it.
- ai.newnal.pdn.server.listAppPasswords query not from the namespace authority List all App Passwords with their OAuth scope. An entry without scope is an unscoped app password created through com.atproto.server.createAppPassword.
- ai.newnal.pdn.server.suggestHandle query not from the namespace authority Suggest free, memorable English two-word handles under this PDN's service domain. A suggestion is not a reservation. Fewer handles than count may be returned; HandleGenerationFailed when none could be found.
- ai.newnal.trustsquare.chatMessage record not from the namespace authority A live-chat message in a Trust Square whose subject is a live stream.
- ai.newnal.trustsquare.comment record not from the namespace authority A comment in a Trust Square. Written only by identity-verified accounts.
- ai.newnal.trustsquare.defs defs What the account holder chose to reveal, signed by the verifier. `ageBand` and `gender` are derived from the verified identity and are therefore attested; `occupation` and `affiliation` are self-declared. With nothing disclosed, `displayName` is the masked form of the verified name.
- ai.newnal.trustsquare.getActorHistory query Everything an account wrote on Trust Square, newest first.
- ai.newnal.trustsquare.getActorProfile query Verification summary and stats for an account.
- ai.newnal.trustsquare.getChatMessages query Page through chat messages of a live Square (newest first by default).
- ai.newnal.trustsquare.getCommentThread query Fetch a comment with all of its replies.
- ai.newnal.trustsquare.getComments query List root comments of a Square with a few inline replies each.
- ai.newnal.trustsquare.getRecordProof query Fetch and verify the repository proof for a record: DID document, commit signature, MST inclusion.
- ai.newnal.trustsquare.getReplies query Page through replies under a root comment.
- ai.newnal.trustsquare.getSocialAccounts query Social accounts an actor has linked, in a stable platform order.
- ai.newnal.trustsquare.getSquare query Fetch one Square by AT-URI or short id.
- ai.newnal.trustsquare.getSquares query Squares across the service, most recently active first. Used to suggest other conversations to a reader; while few Squares exist this is the whole list rather than a ranked selection.
- ai.newnal.trustsquare.getSquaresByVideo query List Squares attached to a YouTube video.
- ai.newnal.trustsquare.getVerificationStatus query Current verification status of an account as known to the AppView.
- ai.newnal.trustsquare.moderationAction record not from the namespace authority A moderation action by a Square owner on content in their Square.
- ai.newnal.trustsquare.reaction record not from the namespace authority A like or dislike on a comment or chat message. One active reaction per author per subject; the AppView keeps the newest.
- ai.newnal.trustsquare.socialAccount record A social account the holder claims as theirs. The record key is the platform id, so a repository can hold at most one account per platform. `method` records how the claim was established: `mock` means it was auto-accepted by the mocked flow and proves nothing, so consumers must not present it as ownership-checked once real methods exist.
- ai.newnal.trustsquare.square record not from the namespace authority A Trust Square: a verified-only comment/chat space attached to one piece of external content.
- ai.newnal.trustsquare.verification record not from the namespace authority Public, PII-free proof that this account passed identity verification with the Newnal verifier. The attestation is a compact JWS signed by the issuer; the AppView rejects records whose signature or payload does not match.