At this level
ai.newnal.illi · 7- ai.newnal.illi.deviceApp permission-set
- ai.newnal.illi.deviceAppPrivate permission-set
- 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.familyApp permission-set
- ai.newnal.illi.familyAppPrivate permission-set
- ai.newnal.illi.service space Registry of ILLI accounts, devices, homes and links, owned by the ILLI service account. One space per environment; the skey is the environment name (dev, prod).
- ai.newnal.illi.serviceSync permission-set
- 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.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.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.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.illi.home.listMine query Homes the signed-in account belongs to, with role, device and parents.
- ai.newnal.illi.home.removeMember procedure Remove a member (root admin: any non-root; main admin: members only). Their media are hidden; mirrors updated.
- ai.newnal.illi.home.removeMyPhoto procedure Remove the caller's photo in one home: the caller's own My Data profile in the home's family sphere is rewritten without it.
- ai.newnal.illi.home.rename procedure Rename the home (root or main admin).
- ai.newnal.illi.home.revokeInvite procedure Revoke an invite (root admin).
- ai.newnal.illi.home.setCustodyKey procedure Publish the root admin's X25519 custody public key on their member record; the private key stays in the root admin's Private Sphere.
- ai.newnal.illi.home.setRole procedure Appoint or demote a main admin (root admin).
- ai.newnal.illi.home.updateMyProfile procedure Set the caller's own name and relationship in a home, as the family and the device see them (root admin, main admins and members; parents use parent.putSlot / putProfile). Updates the member mirror record.
- ai.newnal.illi.home.uploadMyPhoto procedure Set the caller's photo in one home (family members; parents use parent.uploadProfileImage). The binary body accepts JPEG, PNG, WebP, HEIC or HEIF, at most 10 MB. The media service synchronously rotates upright, scales the longest side to at most 1024 px without enlargement and returns a metadata-free JPEG (no EXIF, GPS, XMP or ICC), at most 5,000,000 bytes. The Service Agent Node uploads this JPEG with the caller's session and writes the caller's My Data profile (ai.newnal.mydata.dev.profile, rk
- ai.newnal.illi.media.defs defs Full media snapshot; additional fields are allowed and retained.
- ai.newnal.illi.media.deleteItem procedure The author deletes an item; the PDN garbage-collects its blobs.
- ai.newnal.illi.media.getItem query Family-only original item. Device sessions are denied with OriginalAccessDenied.
- ai.newnal.illi.media.getOriginal query Server-to-server only. Media fetches an active registered original using a media service JWT with this method as lxm. The response streams the PDN blob with Content-Type and Content-Length. An original whose deletion is in progress answers 503 OriginalUnavailable (retry later); only a missing, deleted or unregistered original answers 404 NotFound, which media treats as final.
- ai.newnal.illi.media.getTodayUploadCount query Persisted photo originals on the current date in the family timezone, including pending/failed/cancelled media registration. Same-file duplicate uploads count once; videos and deleted originals are excluded. Includes remaining uploads to the ten-photo new-work condition.
- ai.newnal.illi.media.listItems query Family-only original album, newest by takenAt. Device sessions are denied with OriginalAccessDenied.
- ai.newnal.illi.media.receiveArtworkEvent procedure Server-to-server only. Called by the Newnal media service with a service JWT (`iss` = the configured media DID, `lxm` = this method). Apps must not call it.
- ai.newnal.illi.media.receiveAssetEvent procedure Server-to-server only. Called by the Newnal media service with a service JWT (`iss` = the configured media DID, `lxm` = this method). Apps must not call it.
- ai.newnal.illi.media.updateItem procedure Only the uploader updates people, note and the manual capture time. takenAt sets a capture time with an offset; clearTakenAt true clears the correction; sending both, or takenAt null, is InvalidRequest; omitting both keeps it. Works already composed keep their composition; the saved values reach the media service for later works. AI fields cannot be edited.
- ai.newnal.illi.media.uploadItem procedure Upload one photo or video. multipart/form-data parts: homeId, file, timezone?, people? (JSON array of {name, relationship?}, at most 20 people), note? (at most 300 graphemes), takenAt? (offset-bearing timestamp). Unknown parts are ignored. A manual takenAt is queued after registration through updateUserInput. Otherwise capture time comes from file metadata, then upload time. Same-file content in one home returns the existing active original across uploaders, ignoring the new people/note/takenAt
- ai.newnal.illi.parent.get query The parents of a home with their slot names and My Data profiles.
- ai.newnal.illi.parent.putProfile procedure Write a linked parent's My Data profile (ai.newnal.mydata.dev.profile, rkey self) into the PARENT's repo in the family sphere, in the parent's name through delegation, and an ILLI dataEntry (who entered it) into the caller's repo. Root/main admins, or the parent from the device (07 F-05).
- ai.newnal.illi.parent.putSlot procedure Set the name and honorific of a linked parent as the family and the device show them (root or main admin). Writes a new parentSlot record into the caller's repo in the family sphere; the newest record per slot wins.
- ai.newnal.illi.parent.requestCreation procedure The root admin asks the device to create the second parent's Newnal ID (07 F-06); the name and honorific given here fill the new parentSlot. The device learns of it by SSE or getState.pendingRequests and completes it with account.parent.signIn {slot: 2}.
- ai.newnal.illi.parent.uploadProfileImage procedure Upload a profile photo to the PARENT's PDN with the parent's delegated session, after checking linkage, permission and delegation. Query homeId and slot name the parent. The binary body accepts JPEG, PNG, WebP, HEIC or HEIF, at most 5 MB. The media service synchronously rotates upright, scales the longest side to at most 1024 px without enlargement and returns a metadata-free JPEG (no EXIF, GPS, XMP or ICC), at most 5,000,000 bytes. The Service Agent Node uploads only that JPEG with the parent's
- ai.newnal.illi.phone.defs defs The home's group room: the device and every family member.
- ai.newnal.illi.phone.getDirectory query Who can be called in a home and through which rooms: the device (with parent 1's MXID, the account it calls with), the parents as shown on the family app's call screen, the family members in join order with relationship, name, photo and their pair room, and the group room. The only Private Phone read: a family app that follows several ILLIs calls it once per home (home.listMine) and maps every room id it is in to its home from the answers. No presence: whether someone is reachable is learned fro
- ai.newnal.illi.phone.registerIdentity procedure Register the caller's Private Phone account (Matrix user ID). Called by a family member from the family app, or by the device with parent 1's device-app session for the account the device calls with. The MXID is taken to belong to the signed-in caller; there is no proof of control. The client creates the account by DID sign-in on a Messaging Node and writes the ILLI enrollment marker first. The Service Agent Node records phoneIdentity in the caller's family spheres and starts room provisioning;
- ai.newnal.illi.private.custodyKey record not from the namespace authority The root admin's X25519 custody private key for one home (rkey = homeId), kept in their Private Sphere so logging out or reinstalling the app does not lose it; the app caches it in the Keystore/Keychain.
- ai.newnal.illi.private.parentCredential record Custody record kept by a home's root admin in their own Private Sphere: the credentials of one of the home's parent accounts, generated on the ILLI device and handed over through the Service Agent Node at link time. rkey <homeId>-<slot>. Used to restore a parent account on a replaced device.
- ai.newnal.illi.private.phoneKey record The author's own Private Phone account, kept in the author's Private Sphere so a reinstalled app, a reset device or a replaced device restores the same Matrix identity. One per person: rkey self (earlier records used rkey = homeId and carry home).
- ai.newnal.illi.service.account record not from the namespace authority An account that has joined the ILLI service. The rkey is the DID.
- ai.newnal.illi.service.device record One ILLI device. The rkey is the device id: the SHA-256 of the unit's UDS-derived public key (the first key of its DICE chain, registered with the Newnal RKP server at manufacture), 64 lowercase hex characters, so the same unit keeps the same id across factory resets; not a manufacturing serial number. The pending onboarding code lives only in the Service Agent Node database.
- ai.newnal.illi.service.home record not from the namespace authority One home: a device and the family around it. The rkey is the homeId, which is also the family sphere's skey.
- ai.newnal.illi.service.homeLink record Mirror of one account's role in one home; rkey <homeId>-<did>. The Service Agent Node database is authoritative; this record exists so the registry can be rebuilt from the sphere.