Skip to content

Generated file

This page is generated from the GraphQL SDL in hadron-server/src/api/graphql/schema/typeDefs.ts. To refresh it, run npm run docs:graphql from the root of this repo.

Code paths below are not local. The descriptions come from doc comments written inside hadron-server, so a path like src/api/assetPublic.ts is relative to the hadron-server repository — there is no such file here. They point at the implementation and are volatile; the durable statement is the description itself.

Convention: ID or URN

Across the GraphQL API, fields that take an entity reference (memoryId, agentId, appId, orgId, a ref argument, or id on an entity-keyed op) accept either the entity's database ID or its URN. URNs may be passed bare (e.g. acme:family-mealplan) or with the optional canonical hrn:<type>: prefix (e.g. hrn:mem:acme:family-mealplan); the legacy urn:<type>: prefix is also accepted on input. All shapes resolve to the same entity, with identical authorization and behavior. The closing line of every in-scope field's description — "Accepts the entity's ID or URN." — calls out which fields participate.

# These two queries are equivalent:
query { memory(ref: "cm5x...kqp") { name } }
query { memory(ref: "acme:family-mealplan") { name } }

Convention: null can mean withheld

On App, the fields members, memberCount, appAgents, agents and hasAiApiKey return null when Hadron withholds them from the caller. That is not the same as empty. See Withheld versus empty.

GraphQL API Reference

Table of Contents * [Query](#query) * [Mutation](#mutation) * [Objects](#objects) * [AccessGrant](#accessgrant) * [AccountUsageAccount](#accountusageaccount) * [AccountUsageAccounts](#accountusageaccounts) * [AccountUsageBurnRange](#accountusageburnrange) * [AccountUsageMoveTarget](#accountusagemovetarget) * [AccountUsageProjection](#accountusageprojection) * [AccountUsageWhatIf](#accountusagewhatif) * [AccountUsageWindowProjection](#accountusagewindowprojection) * [AcknowledgeWakesResult](#acknowledgewakesresult) * [ActionRegisterIndexEntry](#actionregisterindexentry) * [ActionRegisterIndexPage](#actionregisterindexpage) * [ActionTicket](#actionticket) * [ActionTicketsPage](#actionticketspage) * [ActorRef](#actorref) * [AddMemoryMemberPayload](#addmemorymemberpayload) * [Agent](#agent) * [AgentAIConfig](#agentaiconfig) * [AgentExtensionPage](#agentextensionpage) * [AgentImport](#agentimport) * [AgentListedProcess](#agentlistedprocess) * [AgentListedTask](#agentlistedtask) * [AgentMemoryItem](#agentmemoryitem) * [AgentOfferReadiness](#agentofferreadiness) * [AgentOfferReason](#agentofferreason) * [AgentOfferSubject](#agentoffersubject) * [AgentOrgGrant](#agentorggrant) * [AgentSchedule](#agentschedule) * [AgentSchedulePreview](#agentschedulepreview) * [AgentSchedulesPage](#agentschedulespage) * [AgentServedBootPrompt](#agentservedbootprompt) * [AgentSubscription](#agentsubscription) * [AgentSubscriptionPage](#agentsubscriptionpage) * [AgentTask](#agenttask) * [AgentTaskAppliedRunSettings](#agenttaskappliedrunsettings) * [AgentTaskDependencyPage](#agenttaskdependencypage) * [AgentTaskExternalIdChange](#agenttaskexternalidchange) * [AgentTaskExternalIdChangePage](#agenttaskexternalidchangepage) * [AgentTaskFinding](#agenttaskfinding) * [AgentTaskFindingDisposition](#agenttaskfindingdisposition) * [AgentTaskFindingDispositionPage](#agenttaskfindingdispositionpage) * [AgentTaskFindingPage](#agenttaskfindingpage) * [AgentTaskHandBack](#agenttaskhandback) * [AgentTaskMatchFailure](#agenttaskmatchfailure) * [AgentTaskParty](#agenttaskparty) * [AgentTaskReference](#agenttaskreference) * [AgentTaskRequirements](#agenttaskrequirements) * [AgentTaskResult](#agenttaskresult) * [AgentTaskRunSettings](#agenttaskrunsettings) * [AgentTaskSessionEndRequest](#agenttasksessionendrequest) * [AgentTaskSkippedCandidate](#agenttaskskippedcandidate) * [AgentTaskStallSchedule](#agenttaskstallschedule) * [AgentTeamAlarmSchedule](#agentteamalarmschedule) * [AgentTeamEvent](#agentteamevent) * [AgentTeamEventsPage](#agentteameventspage) * [AgentTickerTemplate](#agenttickertemplate) * [AgentWebhook](#agentwebhook) * [AgentWebhookCredentials](#agentwebhookcredentials) * [AgentWebhooksPage](#agentwebhookspage) * [AgentlessSessionEnd](#agentlesssessionend) * [AgentsPage](#agentspage) * [AiConfigTestKnob](#aiconfigtestknob) * [AiModelPrice](#aimodelprice) * [AiModelPriceList](#aimodelpricelist) * [AiProviderEndpoint](#aiproviderendpoint) * [AiServiceConfig](#aiserviceconfig) * [AiServiceConfigTestError](#aiserviceconfigtesterror) * [AiServiceConfigTestResult](#aiserviceconfigtestresult) * [AiServiceConfigTestUsed](#aiserviceconfigtestused) * [AiServiceConfigsPage](#aiserviceconfigspage) * [App](#app) * [AppAIConfig](#appaiconfig) * [AppAgent](#appagent) * [AppCreated](#appcreated) * [AppDeliverySettings](#appdeliverysettings) * [AppGrant](#appgrant) * [AppKey](#appkey) * [AppKeyCreated](#appkeycreated) * [AppKeyPage](#appkeypage) * [AppKeyScope](#appkeyscope) * [AppMember](#appmember) * [AppMemorySource](#appmemorysource) * [AppMemoryWriteGrant](#appmemorywritegrant) * [AppRun](#apprun) * [AppRunFailureReason](#apprunfailurereason) * [AppRunsPage](#apprunspage) * [AppScopedMemory](#appscopedmemory) * [AppScopedMemoryPage](#appscopedmemorypage) * [AppSweepMode](#appsweepmode) * [AppTickerSettings](#apptickersettings) * [AppliedTickerTemplate](#appliedtickertemplate) * [AppliedTickerTemplateTicker](#appliedtickertemplateticker) * [ApplyAgentTickerTemplatesResult](#applyagenttickertemplatesresult) * [ApproveMemoryNodesResult](#approvememorynodesresult) * [AppsPage](#appspage) * [Asset](#asset) * [AssetDownloadUrl](#assetdownloadurl) * [AssetListResult](#assetlistresult) * [AssetPutHeader](#assetputheader) * [AssetsPage](#assetspage) * [AuthContext](#authcontext) * [AutomationApproval](#automationapproval) * [AutomationApprovalOmission](#automationapprovalomission) * [AutomationApprovalPage](#automationapprovalpage) * [AutomationApprovalRow](#automationapprovalrow) * [AutomationFlowSummary](#automationflowsummary) * [AutomationReadGrant](#automationreadgrant) * [AutomationSummary](#automationsummary) * [AutomationTeamSnapshotGrant](#automationteamsnapshotgrant) * [AutomationTeamSnapshotGrantPage](#automationteamsnapshotgrantpage) * [BeginAssetUploadResult](#beginassetuploadresult) * [BootPromptServeDecision](#bootpromptservedecision) * [BootPromptServeOutcome](#bootpromptserveoutcome) * [BootPromptSigningPreview](#bootpromptsigningpreview) * [BootPromptSigningPreviewRow](#bootpromptsigningpreviewrow) * [CalendarAttendee](#calendarattendee) * [CalendarEvent](#calendarevent) * [CalendarEventTime](#calendareventtime) * [CalendarInfo](#calendarinfo) * [CalendarPerson](#calendarperson) * [CancelWebPollPayload](#cancelwebpollpayload) * [CastPreviewTicker](#castpreviewticker) * [CastWorkerPreview](#castworkerpreview) * [Channel](#channel) * [ChannelReadState](#channelreadstate) * [ChannelsPage](#channelspage) * [Chat](#chat) * [ChatAiConfigChoice](#chataiconfigchoice) * [ChatMessage](#chatmessage) * [ChatPage](#chatpage) * [ChatProbeOutcome](#chatprobeoutcome) * [ChatPromptResult](#chatpromptresult) * [ChatResponseResult](#chatresponseresult) * [ChatStartResult](#chatstartresult) * [ClaimUntrackedTaskItemsResult](#claimuntrackedtaskitemsresult) * [Comment](#comment) * [CommentActorRef](#commentactorref) * [CommentAuthor](#commentauthor) * [CommentSummary](#commentsummary) * [CommentTargetRef](#commenttargetref) * [CommentThread](#commentthread) * [CommentThreadPage](#commentthreadpage) * [CompiledBootPrompt](#compiledbootprompt) * [CompiledPromptOccurrence](#compiledpromptoccurrence) * [CompiledPromptProvenancePage](#compiledpromptprovenancepage) * [CompiledPromptSelection](#compiledpromptselection) * [CompiledPromptTagPosition](#compiledprompttagposition) * [ConnectionFlow](#connectionflow) * [ConnectionGrant](#connectiongrant) * [ConnectionGrantsPage](#connectiongrantspage) * [ConnectionStart](#connectionstart) * [ContextReset](#contextreset) * [ContextResetStep](#contextresetstep) * [CreateMemorySharePayload](#creatememorysharepayload) * [CreditBalance](#creditbalance) * [CreditLedgerEntry](#creditledgerentry) * [CreditLedgerEntryList](#creditledgerentrylist) * [DashboardWidget](#dashboardwidget) * [DashboardWidgetData](#dashboardwidgetdata) * [DashboardWidgetPreset](#dashboardwidgetpreset) * [DashboardWidgetPresetPage](#dashboardwidgetpresetpage) * [Decision](#decision) * [DecisionActor](#decisionactor) * [DecisionAnswer](#decisionanswer) * [DecisionApprovalEvidence](#decisionapprovalevidence) * [DecisionEvidence](#decisionevidence) * [DecisionIdentityMerge](#decisionidentitymerge) * [DecisionLog](#decisionlog) * [DecisionOption](#decisionoption) * [DecisionPage](#decisionpage) * [DecisionPart](#decisionpart) * [DecisionPurge](#decisionpurge) * [DecisionRecommendation](#decisionrecommendation) * [DecisionRef](#decisionref) * [DecisionVerification](#decisionverification) * [DecisionWithdrawal](#decisionwithdrawal) * [DefectLink](#defectlink) * [DeleteMemorySharePayload](#deletememorysharepayload) * [DeleteTeamRolePayload](#deleteteamrolepayload) * [DeleteWorkerPreview](#deleteworkerpreview) * [DeliveryBatch](#deliverybatch) * [DeliveryBatchPage](#deliverybatchpage) * [DeliveryBatchRange](#deliverybatchrange) * [DormantWithheld](#dormantwithheld) * [DriveFile](#drivefile) * [DriveFileExport](#drivefileexport) * [DriveFilePage](#drivefilepage) * [DueChannel](#duechannel) * [DueStopReason](#duestopreason) * [DueTaskReason](#duetaskreason) * [DueWake](#duewake) * [DueWakeAvailability](#duewakeavailability) * [DueWakePage](#duewakepage) * [DueWakePageInfo](#duewakepageinfo) * [Edge](#edge) * [EdgesPage](#edgespage) * [EditorLockResult](#editorlockresult) * [EffectiveAccess](#effectiveaccess) * [EffectiveActionPolicy](#effectiveactionpolicy) * [EffectiveModelGroup](#effectivemodelgroup) * [EmailDraftInfo](#emaildraftinfo) * [ExchangeConnection](#exchangeconnection) * [ExchangeConnectionPage](#exchangeconnectionpage) * [ExchangeFolder](#exchangefolder) * [ExchangeMessage](#exchangemessage) * [FindNodesResult](#findnodesresult) * [GlobalSearchHit](#globalsearchhit) * [GlobalSearchResult](#globalsearchresult) * [Grant](#grant) * [GrantAction](#grantaction) * [GrantActionParameter](#grantactionparameter) * [GrantActionsPage](#grantactionspage) * [GrantSignature](#grantsignature) * [GrantSignatureStatus](#grantsignaturestatus) * [GrantSigningRequest](#grantsigningrequest) * [GrantsPage](#grantspage) * [GraphEdge](#graphedge) * [GraphEdgesPage](#graphedgespage) * [GraphNode](#graphnode) * [GraphNodesPage](#graphnodespage) * [HomeAssistantInstance](#homeassistantinstance) * [HomeAssistantInstancesPage](#homeassistantinstancespage) * [HomeAssistantOp](#homeassistantop) * [HostDesiredState](#hostdesiredstate) * [HostKeyUse](#hostkeyuse) * [HostOperation](#hostoperation) * [HostOperationPage](#hostoperationpage) * [HostRegistration](#hostregistration) * [HostRegistrationRefusal](#hostregistrationrefusal) * [HostRegistrationWorker](#hostregistrationworker) * [HostSetup](#hostsetup) * [HostSweepRun](#hostsweeprun) * [HostSweepRunLine](#hostsweeprunline) * [HostWorkerAssignment](#hostworkerassignment) * [ImpersonationInfo](#impersonationinfo) * [ImpersonationSession](#impersonationsession) * [ImpersonationSessionList](#impersonationsessionlist) * [ImportNodeResult](#importnoderesult) * [IndexTruncated](#indextruncated) * [InheritedFrom](#inheritedfrom) * [InstallAgentIntoAppPayload](#installagentintoapppayload) * [InstallationPolicy](#installationpolicy) * [JoinAppPayload](#joinapppayload) * [LeaveAppPayload](#leaveapppayload) * [LiftStopSignalResult](#liftstopsignalresult) * [LintWarning](#lintwarning) * [LintWarningPage](#lintwarningpage) * [LocSegment](#locsegment) * [LocSegmentsPage](#locsegmentspage) * [MarketplaceResourcePage](#marketplaceresourcepage) * [McpServer](#mcpserver) * [McpServerTool](#mcpservertool) * [McpServersPage](#mcpserverspage) * [MemoriesPage](#memoriespage) * [Memory](#memory) * [MemoryConfig](#memoryconfig) * [MemoryConfigApplyEntry](#memoryconfigapplyentry) * [MemoryConfigApplyResult](#memoryconfigapplyresult) * [MemoryConfigBulkApplyEntry](#memoryconfigbulkapplyentry) * [MemoryConfigBulkApplyError](#memoryconfigbulkapplyerror) * [MemoryConfigBulkApplyResult](#memoryconfigbulkapplyresult) * [MemoryConfigDefaultSkip](#memoryconfigdefaultskip) * [MemoryConfigTemplate](#memoryconfigtemplate) * [MemoryConfigTemplatePayload](#memoryconfigtemplatepayload) * [MemoryConfigTemplateRule](#memoryconfigtemplaterule) * [MemoryConfigTemplatesPage](#memoryconfigtemplatespage) * [MemoryConfigWarning](#memoryconfigwarning) * [MemoryIntegrityReport](#memoryintegrityreport) * [MemoryMember](#memorymember) * [MemoryOwnerTransferPreview](#memoryownertransferpreview) * [MemoryProvisioning](#memoryprovisioning) * [MemoryShare](#memoryshare) * [MemorySubscription](#memorysubscription) * [MemoryTransferBlocker](#memorytransferblocker) * [MemoryTransferDependent](#memorytransferdependent) * [MemoryValidationFinding](#memoryvalidationfinding) * [MemoryValidationResult](#memoryvalidationresult) * [MemoryValidationSkippedCheck](#memoryvalidationskippedcheck) * [ModelFamilyAvailability](#modelfamilyavailability) * [ModelGroup](#modelgroup) * [Node](#node) * [NodeApproval](#nodeapproval) * [NodeApprovalReceipt](#nodeapprovalreceipt) * [NodeApprovalStatus](#nodeapprovalstatus) * [NodeAuthorship](#nodeauthorship) * [NodeBatchResult](#nodebatchresult) * [NodeContentValidationReport](#nodecontentvalidationreport) * [NodeContentValidationReportReceipt](#nodecontentvalidationreportreceipt) * [NodeContentValidationStatus](#nodecontentvalidationstatus) * [NodeEdgeRemoval](#nodeedgeremoval) * [NodeExportResult](#nodeexportresult) * [NodeHit](#nodehit) * [NodeIntegrityCheck](#nodeintegritycheck) * [NodeMintStatus](#nodemintstatus) * [NodeMoveLinkWarning](#nodemovelinkwarning) * [NodeMovePlan](#nodemoveplan) * [NodeMovePlanEntry](#nodemoveplanentry) * [NodePage](#nodepage) * [NodeRevision](#noderevision) * [NodeRevisionEditor](#noderevisioneditor) * [NodeRevisionPage](#noderevisionpage) * [NodeRoleRule](#noderolerule) * [NodeRoleRulePayload](#noderolerulepayload) * [NodeRoleRuleSourceTemplate](#noderolerulesourcetemplate) * [NodeSignature](#nodesignature) * [NodeSignatureStatus](#nodesignaturestatus) * [NodeValidationTaskEntry](#nodevalidationtaskentry) * [NodeValidationTaskSet](#nodevalidationtaskset) * [NodeVectorMeta](#nodevectormeta) * [ObjectList](#objectlist) * [OrgBootPromptSigning](#orgbootpromptsigning) * [OrgMember](#orgmember) * [Organization](#organization) * [OrganizationsPage](#organizationspage) * [OwnTeamChatReadState](#ownteamchatreadstate) * [Passage](#passage) * [PasskeyCancelRecord](#passkeycancelrecord) * [PasskeyCredential](#passkeycredential) * [PasskeyWindow](#passkeywindow) * [PolicyLayerVerdict](#policylayerverdict) * [PrProtocolAction](#prprotocolaction) * [PrProtocolResult](#prprotocolresult) * [PrincipalGrant](#principalgrant) * [PrincipalGrantsPage](#principalgrantspage) * [PublicInvitation](#publicinvitation) * [PublicInvitationOrganization](#publicinvitationorganization) * [PublicInvitationSender](#publicinvitationsender) * [PublicOrganization](#publicorganization) * [PublicResourceRef](#publicresourceref) * [PublicResourceRefsPage](#publicresourcerefspage) * [PullRequestReadiness](#pullrequestreadiness) * [QuotaCounter](#quotacounter) * [RateLimitPolicy](#ratelimitpolicy) * [RecordAppActionResult](#recordappactionresult) * [RecoveryEdgesPage](#recoveryedgespage) * [RecoveryEndpoint](#recoveryendpoint) * [RecoveryGraphEdge](#recoverygraphedge) * [RecoveryNode](#recoverynode) * [RecoveryNodeSummary](#recoverynodesummary) * [RecoveryNodesPage](#recoverynodespage) * [RegisterDefaults](#registerdefaults) * [RegisterEntriesPage](#registerentriespage) * [RegisterEntry](#registerentry) * [RegisterRoleCandidate](#registerrolecandidate) * [RegisterRoleCandidatePage](#registerrolecandidatepage) * [RegisterRolePick](#registerrolepick) * [RegisterRouteEntry](#registerrouteentry) * [RegisterViewChannel](#registerviewchannel) * [RegisterViewRow](#registerviewrow) * [ReleaseWorkerPayload](#releaseworkerpayload) * [ReleasedFromUser](#releasedfromuser) * [RemoveMemoryMemberPayload](#removememorymemberpayload) * [ResendSender](#resendsender) * [ResendSendersPage](#resendsenderspage) * [ResolvedAiConfig](#resolvedaiconfig) * [ResumeCandidate](#resumecandidate) * [ResumeClaimReceipt](#resumeclaimreceipt) * [ResumeSessionResult](#resumesessionresult) * [ReviewQualityReport](#reviewqualityreport) * [ReviewQualityRow](#reviewqualityrow) * [ReviewSlotReadiness](#reviewslotreadiness) * [RevisionApproval](#revisionapproval) * [RevisionResult](#revisionresult) * [ScheduleBusyInterval](#schedulebusyinterval) * [ScheduleFreeBusy](#schedulefreebusy) * [Scope](#scope) * [ScopeExplanation](#scopeexplanation) * [ScopeMemoryEntry](#scopememoryentry) * [ScopesPage](#scopespage) * [SearchReplaceFieldResult](#searchreplacefieldresult) * [SearchReplaceNodeResult](#searchreplacenoderesult) * [SearchReplaceResult](#searchreplaceresult) * [SearchReplaceSkip](#searchreplaceskip) * [SearchReplaceSkipCounts](#searchreplaceskipcounts) * [SearchScopeInfo](#searchscopeinfo) * [Secret](#secret) * [SecretEvent](#secretevent) * [SecretEventsPage](#secreteventspage) * [SecretVersion](#secretversion) * [SecretVersionsPage](#secretversionspage) * [SecretsPage](#secretspage) * [ServedPrompt](#servedprompt) * [ServedPromptProvenanceEntry](#servedpromptprovenanceentry) * [ServedPromptProvenancePage](#servedpromptprovenancepage) * [ServedPromptsPage](#servedpromptspage) * [ServerInfo](#serverinfo) * [Session](#session) * [SessionPage](#sessionpage) * [SetHostWorkerTerminalsResult](#sethostworkerterminalsresult) * [SharedOrganization](#sharedorganization) * [SharedOrganizationsPage](#sharedorganizationspage) * [SigningRequest](#signingrequest) * [SigningRequester](#signingrequester) * [SigningRequestsPage](#signingrequestspage) * [SkillExportPlanEntry](#skillexportplanentry) * [SkillExportReason](#skillexportreason) * [SkillFinding](#skillfinding) * [SkillOrphan](#skillorphan) * [SkillPlan](#skillplan) * [SkillPlanEntry](#skillplanentry) * [SkillPlanScopeSelection](#skillplanscopeselection) * [SkillPlanUnrecognized](#skillplanunrecognized) * [SkillSelectionResult](#skillselectionresult) * [SlackConnection](#slackconnection) * [SlackConnectionsPage](#slackconnectionspage) * [SpecCorpusMintReport](#speccorpusmintreport) * [SpecDocument](#specdocument) * [SpecDocumentEntry](#specdocumententry) * [SpecMintFinding](#specmintfinding) * [SpecOpenQuestion](#specopenquestion) * [SpecOpenQuestionGroup](#specopenquestiongroup) * [SpecReference](#specreference) * [SpecReferencePage](#specreferencepage) * [SpecRenumberMove](#specrenumbermove) * [SpecRenumberResult](#specrenumberresult) * [SpecRenumberRewrite](#specrenumberrewrite) * [SpecTextCitation](#spectextcitation) * [StartImpersonationResult](#startimpersonationresult) * [StopSignal](#stopsignal) * [StopSignalPage](#stopsignalpage) * [SubscribeResult](#subscriberesult) * [SummarizationRequest](#summarizationrequest) * [TeamAttentionChannel](#teamattentionchannel) * [TeamAttentionPage](#teamattentionpage) * [TeamAttentionPageItem](#teamattentionpageitem) * [TeamAttentionPreviewPage](#teamattentionpreviewpage) * [TeamAttentionResult](#teamattentionresult) * [TeamAttentionSwitchoverChannel](#teamattentionswitchoverchannel) * [TeamAttentionSwitchoverPreview](#teamattentionswitchoverpreview) * [TeamAttentionSwitchoverResult](#teamattentionswitchoverresult) * [TeamAttentionSwitchoverWorker](#teamattentionswitchoverworker) * [TeamAttentionWorker](#teamattentionworker) * [TeamAvailability](#teamavailability) * [TeamChatMessage](#teamchatmessage) * [TeamChatMessagesPage](#teamchatmessagespage) * [TeamChatSearchMatch](#teamchatsearchmatch) * [TeamChatSearchPage](#teamchatsearchpage) * [TeamCollectionsPayload](#teamcollectionspayload) * [TeamComposition](#teamcomposition) * [TeamCompositionLane](#teamcompositionlane) * [TeamCompositionWorker](#teamcompositionworker) * [TeamPause](#teampause) * [TeamRole](#teamrole) * [TeamRoleCount](#teamrolecount) * [TeamRoleFamilyCount](#teamrolefamilycount) * [TeamRolesPage](#teamrolespage) * [TeamRoster](#teamroster) * [TeamRosterEntry](#teamrosterentry) * [TeamRosterTaskSummary](#teamrostertasksummary) * [TeamTagSnapshot](#teamtagsnapshot) * [TeamUtilization](#teamutilization) * [TeamWorkItem](#teamworkitem) * [TeamWorkItemsPage](#teamworkitemspage) * [TickAction](#tickaction) * [Ticker](#ticker) * [TickerPage](#tickerpage) * [TickerSubscription](#tickersubscription) * [TickerSubscriptionPage](#tickersubscriptionpage) * [UninstallAgentFromAppPayload](#uninstallagentfromapppayload) * [UnresolvedFeedback](#unresolvedfeedback) * [UntrackedTaskItem](#untrackedtaskitem) * [UntrackedTaskItemPage](#untrackedtaskitempage) * [UpdateMemoryMemberRolePayload](#updatememorymemberrolepayload) * [UpdateMemoryShareRolePayload](#updatememorysharerolepayload) * [UrnResolution](#urnresolution) * [UsageActivityBucket](#usageactivitybucket) * [UsageEvent](#usageevent) * [UsageEventPage](#usageeventpage) * [UsageSummaryEntry](#usagesummaryentry) * [User](#user) * [UserApiKey](#userapikey) * [UserApiKeyCreateResult](#userapikeycreateresult) * [UserApiKeyDeletion](#userapikeydeletion) * [UserApiKeyPage](#userapikeypage) * [UserInvitation](#userinvitation) * [UserMergeConsentRequest](#usermergeconsentrequest) * [UsersPage](#userspage) * [WakeReason](#wakereason) * [WebPoll](#webpoll) * [WebPollsPage](#webpollspage) * [Worker](#worker) * [WorkerAvailability](#workeravailability) * [WorkerCheckStatus](#workercheckstatus) * [WorkerContinuity](#workercontinuity) * [WorkerContinuitySession](#workercontinuitysession) * [WorkerDesiredState](#workerdesiredstate) * [WorkerHolder](#workerholder) * [WorkerLeaveAlone](#workerleavealone) * [WorkerRunSettings](#workerrunsettings) * [WorkerTerminal](#workerterminal) * [WorkerTerminalHost](#workerterminalhost) * [WorkerTerminalRef](#workerterminalref) * [WorkerTerminalRefusal](#workerterminalrefusal) * [WorkerUtilization](#workerutilization) * [WorkerWakeSettings](#workerwakesettings) * [WorkersPage](#workerspage) * [Inputs](#inputs) * [AccountUsageMoveWorkerInput](#accountusagemoveworkerinput) * [AccountUsageWhatIfInput](#accountusagewhatifinput) * [ActInstructionInput](#actinstructioninput) * [AgentFilter](#agentfilter) * [AgentTaskFindingInput](#agenttaskfindinginput) * [AgentTaskHandBackInput](#agenttaskhandbackinput) * [AgentTaskPartyInput](#agenttaskpartyinput) * [AgentTaskReferenceFilter](#agenttaskreferencefilter) * [AgentTaskReferenceInput](#agenttaskreferenceinput) * [AgentTaskRequirementsInput](#agenttaskrequirementsinput) * [AgentTaskResultInput](#agenttaskresultinput) * [AgentTaskRunSettingsInput](#agenttaskrunsettingsinput) * [AgentTaskStallScheduleInput](#agenttaskstallscheduleinput) * [AgentTickerTemplateInput](#agenttickertemplateinput) * [AgentTickerTemplatePatch](#agenttickertemplatepatch) * [AiServiceConfigFilter](#aiserviceconfigfilter) * [AiServiceConfigTestOverride](#aiserviceconfigtestoverride) * [AmendDecisionInput](#amenddecisioninput) * [AppDeliverySettingsInput](#appdeliverysettingsinput) * [AppFilter](#appfilter) * [AppTickerSettingsInput](#apptickersettingsinput) * [AskDecisionInput](#askdecisioninput) * [AssetFilter](#assetfilter) * [AssignHostWorkerInput](#assignhostworkerinput) * [AuthoredWithInput](#authoredwithinput) * [AuthorizeContextResetStopInput](#authorizecontextresetstopinput) * [BatchThrough](#batchthrough) * [BeginAssetUploadInput](#beginassetuploadinput) * [BeginAssetUploadV2Input](#beginassetuploadv2input) * [CalendarEventTimeInput](#calendareventtimeinput) * [ChannelFilter](#channelfilter) * [ClaimContextResetInput](#claimcontextresetinput) * [CloneAgentTaskInput](#cloneagenttaskinput) * [CompleteAssetUploadInput](#completeassetuploadinput) * [ContextResetCheckpointInput](#contextresetcheckpointinput) * [ContextResetStepInput](#contextresetstepinput) * [CreateAgentScheduleInput](#createagentscheduleinput) * [CreateAgentTaskInput](#createagenttaskinput) * [CreateAgentTasksItemInput](#createagenttasksiteminput) * [CreateAgentWebhookInput](#createagentwebhookinput) * [CreateAssetReferenceNodeInput](#createassetreferencenodeinput) * [CreateChannelInput](#createchannelinput) * [CreateGrantInput](#creategrantinput) * [CreateMemoryConfigTemplateInput](#creatememoryconfigtemplateinput) * [CreateNodeInput](#createnodeinput) * [CreateNodeRoleRuleInput](#createnoderoleruleinput) * [CreateRegisterEntryInput](#createregisterentryinput) * [CreateScopeInput](#createscopeinput) * [DashboardWidgetInput](#dashboardwidgetinput) * [DecisionNoRecommendationInput](#decisionnorecommendationinput) * [DecisionOptionInput](#decisionoptioninput) * [DecisionPartInput](#decisionpartinput) * [DecisionPartPatchInput](#decisionpartpatchinput) * [DecisionRecommendationInput](#decisionrecommendationinput) * [DecisionRefInput](#decisionrefinput) * [EdgeFilter](#edgefilter) * [EdgeInput](#edgeinput) * [EndAgentlessSessionInput](#endagentlesssessioninput) * [GrantCreditsInput](#grantcreditsinput) * [HostSweepRunLineInput](#hostsweeprunlineinput) * [ImpersonationSessionFilter](#impersonationsessionfilter) * [ImportNodeInput](#importnodeinput) * [InstallTargetInput](#installtargetinput) * [IssueHostOperationInput](#issuehostoperationinput) * [MemoryConfigTemplateFilter](#memoryconfigtemplatefilter) * [MemoryFilter](#memoryfilter) * [MergeMemoriesInput](#mergememoriesinput) * [MergeNodesInput](#mergenodesinput) * [MergeUsersInput](#mergeusersinput) * [MintActionTicketsInput](#mintactionticketsinput) * [NodeEdgeInput](#nodeedgeinput) * [NodeFilter](#nodefilter) * [NodeInput](#nodeinput) * [NodePropertySort](#nodepropertysort) * [NodeWhereInput](#nodewhereinput) * [ObservedProcessInput](#observedprocessinput) * [OrganizationFilter](#organizationfilter) * [PreviewAgentScheduleInput](#previewagentscheduleinput) * [PublicAgentFilter](#publicagentfilter) * [RecordHostSweepRunInput](#recordhostsweepruninput) * [RegisterContextResetRecoveryInput](#registercontextresetrecoveryinput) * [RegisterDefaultsInput](#registerdefaultsinput) * [RegisterEntryFilter](#registerentryfilter) * [RegisterHostInput](#registerhostinput) * [RegisterHostWorkerInput](#registerhostworkerinput) * [ReportContextResetRelaunchFailedInput](#reportcontextresetrelaunchfailedinput) * [ReportContextResetRelaunchedInput](#reportcontextresetrelaunchedinput) * [ReportHostOperationInput](#reporthostoperationinput) * [ResumeSessionInput](#resumesessioninput) * [ScopeFilter](#scopefilter) * [SearchReplaceInNodesInput](#searchreplaceinnodesinput) * [SelectedSkillFilePlanInput](#selectedskillfileplaninput) * [SessionInput](#sessioninput) * [SetAgentAssetUploadEnabledInput](#setagentassetuploadenabledinput) * [SetAiModelPriceInput](#setaimodelpriceinput) * [SetHostWorkerAvailabilityInput](#sethostworkeravailabilityinput) * [SetHostWorkerTerminalsInput](#sethostworkerterminalsinput) * [SetModelFamilyAvailabilityInput](#setmodelfamilyavailabilityinput) * [SetQuotaLimitInput](#setquotalimitinput) * [SetRateLimitPolicyInput](#setratelimitpolicyinput) * [SetTeamStopSignalInput](#setteamstopsignalinput) * [SetWorkerAvailabilityInput](#setworkeravailabilityinput) * [SetWorkerLeaveAloneInput](#setworkerleavealoneinput) * [SkillFileFactsInput](#skillfilefactsinput) * [SkillPlanInput](#skillplaninput) * [SpecSearchReplaceInput](#specsearchreplaceinput) * [TickerInput](#tickerinput) * [TickerPatch](#tickerpatch) * [TriggerAppRunInput](#triggerappruninput) * [UnassignHostWorkerInput](#unassignhostworkerinput) * [UpdateAgentScheduleInput](#updateagentscheduleinput) * [UpdateAgentTaskInput](#updateagenttaskinput) * [UpdateChannelInput](#updatechannelinput) * [UpdateMemoryConfigTemplateInput](#updatememoryconfigtemplateinput) * [UpdateNodeInput](#updatenodeinput) * [UpdateNodeRoleRuleInput](#updatenoderoleruleinput) * [UpdateRegisterEntryInput](#updateregisterentryinput) * [UpdateScopeInput](#updatescopeinput) * [UsageEventInput](#usageeventinput) * [UserFilter](#userfilter) * [WorkerTerminalReportInput](#workerterminalreportinput) * [WorkerWakeSettingsInput](#workerwakesettingsinput) * [Enums](#enums) * [AccessSource](#accesssource) * [AccountUsageConfidence](#accountusageconfidence) * [AccountUsageReason](#accountusagereason) * [AccountUsageShape](#accountusageshape) * [AccountUsageStatus](#accountusagestatus) * [AccountUsageWindow](#accountusagewindow) * [ActInstructionKind](#actinstructionkind) * [ActionRegisterIndexState](#actionregisterindexstate) * [AgentLifecycle](#agentlifecycle) * [AgentOfferReasonCode](#agentofferreasoncode) * [AgentProcessKind](#agentprocesskind) * [AgentSchedulePreviewOutcome](#agentschedulepreviewoutcome) * [AgentSchedulePreviewReason](#agentschedulepreviewreason) * [AgentTaskCreateStatus](#agenttaskcreatestatus) * [AgentTaskExternalIdChangeKind](#agenttaskexternalidchangekind) * [AgentTaskFindingDispositionCode](#agenttaskfindingdispositioncode) * [AgentTaskFindingSeverity](#agenttaskfindingseverity) * [AgentTaskHandBackCode](#agenttaskhandbackcode) * [AgentTaskMatchSkipReason](#agenttaskmatchskipreason) * [AgentTaskMatchedBy](#agenttaskmatchedby) * [AgentTaskPartyKind](#agenttaskpartykind) * [AgentTaskReferenceKind](#agenttaskreferencekind) * [AgentTaskSessionEndResolution](#agenttasksessionendresolution) * [AgentTaskStatus](#agenttaskstatus) * [AgentTeamEventSeverity](#agentteameventseverity) * [AgentType](#agenttype) * [AgentVisibility](#agentvisibility) * [AgentlessEndReason](#agentlessendreason) * [AiApiStyle](#aiapistyle) * [AiConfigOwnerType](#aiconfigownertype) * [AiConfigTestKeySource](#aiconfigtestkeysource) * [AiConfigTestValueSource](#aiconfigtestvaluesource) * [AppGrantName](#appgrantname) * [AppMembershipRole](#appmembershiprole) * [AppMemoryKind](#appmemorykind) * [AppMemorySourceKind](#appmemorysourcekind) * [AppRunSortField](#apprunsortfield) * [AppRunStatus](#apprunstatus) * [AppRunTriggerKind](#appruntriggerkind) * [AppType](#apptype) * [AssetScanStatus](#assetscanstatus) * [AuthenticationStatus](#authenticationstatus) * [AutomationAdoptionState](#automationadoptionstate) * [AutomationTriggerKind](#automationtriggerkind) * [AvailabilityReason](#availabilityreason) * [AvailabilitySetter](#availabilitysetter) * [AvailabilityState](#availabilitystate) * [BootPromptServeRefusal](#bootpromptserverefusal) * [BootPromptSigningPreviewState](#bootpromptsigningpreviewstate) * [CalendarEventResponse](#calendareventresponse) * [ChannelKind](#channelkind) * [ChatProbeStatus](#chatprobestatus) * [ChatScope](#chatscope) * [ChatToolChoice](#chattoolchoice) * [CommentAuthorKind](#commentauthorkind) * [CommentThreadState](#commentthreadstate) * [ConnectionFlowStatus](#connectionflowstatus) * [ConnectionProvider](#connectionprovider) * [ContentValidator](#contentvalidator) * [CorpusState](#corpusstate) * [CreateUserPermission](#createuserpermission) * [DashboardWidgetType](#dashboardwidgettype) * [DecisionAnswerVia](#decisionanswervia) * [DecisionSort](#decisionsort) * [DecisionState](#decisionstate) * [DecisionTier](#decisiontier) * [DecisionUrgency](#decisionurgency) * [DesiredRunState](#desiredrunstate) * [DesiredStateReason](#desiredstatereason) * [DriveExportFormat](#driveexportformat) * [DriveFileKind](#drivefilekind) * [DueWakeStatus](#duewakestatus) * [EdgeGovernedKind](#edgegovernedkind) * [EffortLevel](#effortlevel) * [EmailFlag](#emailflag) * [EmbeddingSource](#embeddingsource) * [FindNodesMode](#findnodesmode) * [GrantAnnouncement](#grantannouncement) * [GrantHolderKind](#grantholderkind) * [GrantSignatureState](#grantsignaturestate) * [GrantSigningRequestState](#grantsigningrequeststate) * [GrantState](#grantstate) * [HostOperationIssuer](#hostoperationissuer) * [HostOperationOutcome](#hostoperationoutcome) * [HostOperationStatus](#hostoperationstatus) * [HostSetupSource](#hostsetupsource) * [IdentifyUserMethod](#identifyusermethod) * [ImportNodeStatus](#importnodestatus) * [InstallMethod](#installmethod) * [LintKind](#lintkind) * [MemoryClass](#memoryclass) * [MemoryConfigApplyOutcome](#memoryconfigapplyoutcome) * [MemoryConfigTemplateOwnerType](#memoryconfigtemplateownertype) * [MemoryMemberRole](#memorymemberrole) * [MemoryShareRole](#memorysharerole) * [MemoryTransferHandling](#memorytransferhandling) * [MemoryValidationCheck](#memoryvalidationcheck) * [MemoryVisibility](#memoryvisibility) * [MentionWake](#mentionwake) * [ModelGroupOrigin](#modelgrouporigin) * [NodeApprovalState](#nodeapprovalstate) * [NodeAuthorshipKind](#nodeauthorshipkind) * [NodeContentScope](#nodecontentscope) * [NodeContentValidationAuthorCheck](#nodecontentvalidationauthorcheck) * [NodeContentValidationOutcome](#nodecontentvalidationoutcome) * [NodeContentValidationState](#nodecontentvalidationstate) * [NodeExportEncoding](#nodeexportencoding) * [NodeExportFormat](#nodeexportformat) * [NodeExportSection](#nodeexportsection) * [NodeField](#nodefield) * [NodeIntegrityState](#nodeintegritystate) * [NodeMergeField](#nodemergefield) * [NodeMoveLinkStatus](#nodemovelinkstatus) * [NodeRoleRuleRefState](#noderolerulerefstate) * [NodeRoleWriters](#noderolewriters) * [NodeSort](#nodesort) * [NodeTextField](#nodetextfield) * [NodeValidationTaskSetState](#nodevalidationtasksetstate) * [NodeWhereCast](#nodewherecast) * [NodeWhereColumn](#nodewherecolumn) * [PrincipalType](#principaltype) * [RateLimitEnforcementMode](#ratelimitenforcementmode) * [RateLimitFieldClass](#ratelimitfieldclass) * [ReadyFilter](#readyfilter) * [RegisterDisclosure](#registerdisclosure) * [RegisterNamedBy](#registernamedby) * [RegisterOwnerType](#registerownertype) * [RegisterRole](#registerrole) * [RegisterRouteKind](#registerroutekind) * [ResumeOutcome](#resumeoutcome) * [ResumeSource](#resumesource) * [ReviewVerdict](#reviewverdict) * [Role](#role) * [ScopeOwnerType](#scopeownertype) * [SearchEntityType](#searchentitytype) * [SearchField](#searchfield) * [SearchGranularity](#searchgranularity) * [SearchReplaceSkipReason](#searchreplaceskipreason) * [ServedPromptKind](#servedpromptkind) * [ServedPromptPointerLevel](#servedpromptpointerlevel) * [SessionEndReason](#sessionendreason) * [SessionState](#sessionstate) * [SignatureState](#signaturestate) * [SigningRequestState](#signingrequeststate) * [SkillExportAction](#skillexportaction) * [SkillPlanIntent](#skillplanintent) * [SortDirection](#sortdirection) * [SpecMintFindingKind](#specmintfindingkind) * [SpecReferenceKind](#specreferencekind) * [SpecReferenceProblem](#specreferenceproblem) * [SpecRewriteStatus](#specrewritestatus) * [SpecTextField](#spectextfield) * [StopNoticeKind](#stopnoticekind) * [StopSignalEndKind](#stopsignalendkind) * [StopSignalLevel](#stopsignallevel) * [StopSignalScope](#stopsignalscope) * [SubscriptionType](#subscriptiontype) * [SweepMode](#sweepmode) * [SweepRunOutcome](#sweeprunoutcome) * [SyncStatus](#syncstatus) * [TaskWakeEvent](#taskwakeevent) * [TeamRosterState](#teamrosterstate) * [TeamSpecForm](#teamspecform) * [TickActionState](#tickactionstate) * [TickerReason](#tickerreason) * [TickerRelevance](#tickerrelevance) * [TickerSubscriptionEndReason](#tickersubscriptionendreason) * [UploadIntent](#uploadintent) * [UsageActivityBucketSize](#usageactivitybucketsize) * [WakeKind](#wakekind) * [WorkerCheckState](#workercheckstate) * [WorkerContinuityStatus](#workercontinuitystatus) * [WorkerNoSessionReason](#workernosessionreason) * [WorkerPendingReason](#workerpendingreason) * [WorkerTeamPlacement](#workerteamplacement) * [WorkerTerminalPrompt](#workerterminalprompt) * [WorkerTerminalReason](#workerterminalreason) * [WorkerTerminalRepair](#workerterminalrepair) * [WorkerTerminalRepairReason](#workerterminalrepairreason) * [WorkerTerminalState](#workerterminalstate) * [Scalars](#scalars) * [Boolean](#boolean) * [DateTime](#datetime) * [Float](#float) * [ID](#id) * [Int](#int) * [JSON](#json) * [String](#string)

Query

Field Argument Type Description
pullRequestReadiness PullRequestReadiness #3448 — task readers, including the App's own live key (hrn:node:hadronmemory.com:specs:cor:agt:050:21 / hrn:node:hadronmemory.com:specs:cor:agt:050:23). Null for an unreadable task. PR_HEAD_NOT_FROZEN or REVIEW_SCHEDULE_MISSING for absent event facts.
taskRef ID!
head String!
rateLimitPolicies [RateLimitPolicy!]! Live platform ADMIN/OWNER human only; bounded five-row policy read (#1793).
compiledPromptProvenance CompiledPromptProvenancePage Recorded source revisions for exactly revNo of a compiled boot prompt (hrn:node:hadronmemory.com:specs:cor:agt:040:12). Uses the compiled node's read gate; denied, missing, deleted or noncompiled nodes return null. Provenance survives pruning; pruned marks absent revision text. Source status is null when unreadable. No source text is returned. Limit defaults to 20, clamps to 0..100; offset defaults to 0 and clamps negative values to 0. A missing or malformed provenance record is an integrity error, never an empty page.
nodeRef ID!
revNo Int!
limit Int
offset Int
recoveryNode RecoveryNode Read a retained deleted node in a live memory that you can read and write. Returns the stored body without expanding templates or includes. hrn:node:hadronmemory.com:specs:cor:dmo:010:04
nodeRef ID!
recoveryNodes RecoveryNodesPage! Page through retained deleted nodes you can recover. Default 20, maximum 200; total counts all accessible results. No timed purge. hrn:node:hadronmemory.com:specs:cor:api:120:04
memoryRef ID!
limit Int
offset Int
recoveryEdges RecoveryEdgesPage! Inspect live edges and accessible deleted endpoints in one memory you can read and write. Default 20, maximum 200. edgeIds (1 to 200 ids) restricts the result, total included, to those edges; an id that is not a visible edge of this memory is absent. hrn:node:hadronmemory.com:specs:cor:api:110:02
memoryRef ID!
edgeIds [ID!]
limit Int
offset Int
previewAutomation JSON! #1719: review exact automation graph bytes and digest. triggerRef is the trigger row ID; MANUAL uses the origin AppRun ID. Only its run-as user or the manager of an App-only trigger may preview.
triggerKind AutomationTriggerKind!
triggerRef String!
previewAgentSchedule AgentSchedulePreview! #3457: what a schedule would do before it exists (org ADMIN of the App, checked first; writes nothing). Admin, App, Agent and timing refusals are createAgentSchedule's errors; an entry create would store UNADOPTED is the typed outcome CANNOT_BE_ADOPTED.
input PreviewAgentScheduleInput!
automationApprovals AutomationApprovalPage! #2441: the schedules and webhooks of an App that the caller may adopt, with their adoption state. Authorization first, then ordered by (name, kind, id) and paged: limit defaults to 20, maximum 50; after is the previous page's nextCursor. MANUAL triggers are never listed (consent is per run); omitted says so. Only an adopter sees any row.
appRef String!
limit Int
after String
automationApproval AutomationApproval! #2441: state, hash, plain summary and graph depth for one trigger. MANUAL takes the origin run id. Same gate as approveAutomation.
triggerKind AutomationTriggerKind!
triggerRef String!
appMemoryWriteGrants [AppMemoryWriteGrant!]! #2484: the write grants an App holds for its userless runs, oldest first; revoked rows only with includeRevoked. Only whoever manages the App may list them, as themselves or through their held worker on a validated instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12 S6, ruling 0111 A: one team event per admitted instructed call, never a grant id); a grant on a personal or private memory is listed to the holder alone, when they own it. hrn:node:hadronmemory.com:specs:cor:agt:010:01
appRef String!
includeRevoked Boolean
instruction ActInstructionInput
automationTeamSnapshotGrants AutomationTeamSnapshotGrantPage! #3350: only this App's managers list its team snapshot grants; includeRevoked defaults false. Optional triggerKind (SCHEDULE or WEBHOOK) and triggerId narrow rows and total; triggerId requires triggerKind. Unknown or foreign triggers give an empty page. Authority is checked before filter validation. A held worker on a validated instruction may list within its own App; one ids-only team event per admitted instructed call, including an empty page.
appRef ID!
triggerKind String
triggerId ID
includeRevoked Boolean
limit Int
offset Int
instruction ActInstructionInput
automationTeamSnapshotGrant AutomationTeamSnapshotGrant! #3381: read one grant's eight metadata fields by id, including revoked rows. Only a person managing the grant's own App; no worker instruction arm. Unknown and unauthorized ids both refuse NOT_FOUND with the same message. hrn:node:hadronmemory.com:specs:cor:agt:050:23
id ID!
automationReadGrants [AutomationReadGrant!]! #2883: automation read grants. Give an App (its managers see its grants) and/or a memory (that memory's manager, or an Agent's manager for its system memory, sees the grants on it); a reader sees only the rows they manage the App or the target of. A held worker on a validated instruction is scoped to its own App, including memory-only lists; each admitted instructed list records one ids-only team event. A person supplying instruction must also supply appRef; omit instruction to retain a cross-App memory-only list.
appRef String
memoryRef String
includeRevoked Boolean
instruction ActInstructionInput
agentTask AgentTask #1705 — one agent task, or null when it does not exist or the caller may not read it (no existence oracle). Readers: the App's participants, workers acting through their sessions included (hrn:node:hadronmemory.com:specs:cor:agt:050:21).
id ID!
tickers [Ticker!]! #1747 — the live tickers of an App the caller participates in. An App the caller cannot reach reads as APP_NOT_FOUND (hrn:node:hadronmemory.com:specs:cor:agt:080:18). #2931 — the App's own live host:operate key reads too, read only and never over MCP: only the tickers a worker its host registers subscribes to, each read recorded as a host-key use (hrn:node:hadronmemory.com:specs:cor:agt:070:04, hrn:node:hadronmemory.com:specs:cor:agt:070:07).
appRef String!
tickersPage TickerPage! #2213 — `tickers` as a page: the same App gate, rows and order, with the real total (for a host key, #2931, its host's tickers). `limit` defaults to 20, 0 returns the count only, a negative limit is 0 and a limit over 200 is served as 200 (never refused). `offset` below 0 is 0.
appRef String!
limit Int
offset Int
ticker Ticker #1747 — one ticker by id or hrn:ticker: URN; null when it does not exist or the caller may not reach it. #2931: a host key reaches only its host's tickers (hrn:node:hadronmemory.com:specs:cor:agt:070:04).
ref String!
appTickerSettings AppTickerSettings! #1747 — an App's ticker settings: the cadence floor, the default self-subscription cadence, the live-ticker cap and the daily wake budget (hrn:node:hadronmemory.com:specs:cor:agt:080:05).
appRef String!
appDeliverySettings AppDeliverySettings! App delivery settings for participants; cadence/window is the ticker floor (hrn:node:hadronmemory.com:specs:cor:agt:080:05).
appRef String!
workerWakeSettings WorkerWakeSettings! #1747 — one worker's wake settings (defaults when it has none), readable by the App's participants (hrn:node:hadronmemory.com:specs:cor:agt:080:03).
workerRef String!
dueWakes DueWakePage! #1748 — the wakes due now (hrn:node:hadronmemory.com:specs:cor:agt:080:08). Counts and seq ranges only; reads nothing it does not return. accepts (#2169, hrn:node:hadronmemory.com:specs:cor:agt:090:04): the reason kinds this caller can deliver. Omit it and no STOP notice is ever returned (the shipped ticker-wake). A call that lists STOP is offered the worker's newest undelivered stop notice, and declares the lane it serves (a host key: its own registration; a person who manages the App, or a key without a host: the unhosted lane) for STOP_CONSUMER_FRESH_SECONDS (default 600), but only when it read the lane from its start to its end in one call: no workerRefs, no after, and no next page (ask for first: 200; a lane larger than a page cannot declare). A worker whose host is lost has no serving lane until the host returns. Setting a stop signal is refused (STOP_SIGNAL_UNAVAILABLE) while any worker it would cover is on a lane with no fresh declaration. #3321: the manager's held worker reads the manager scope on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event per admitted call, ids only; it never reads its holder's personal scope, and never acknowledges. #3455: preview: true is the no-spend read (default false = the read above, unchanged). It reserves no wake and counts no budget use (hrn:node:hadronmemory.com:specs:cor:agt:080:15), withholds nothing and posts no budget notice, declares no stop lane, and returns an empty proof, which acknowledges nothing. It reads exactly what the spending read may read, with the same reach and refusals; an App key's preview is still a read the key is recorded for (hrn:node:hadronmemory.com:specs:cor:agt:080:22).
appRef String!
workerRefs [String!]
first Int
after String
accepts [WakeKind!]
instruction ActInstructionInput
preview Boolean
teamStopSignals StopSignalPage! #2022 (hrn:node:hadronmemory.com:specs:cor:agt:090:07) — an App's stop signals, oldest set first. A person in the App sees every signal (worker narrows to those covering that worker now); a worker's session sees the live ones covering it; a host key sees its own host's. includeEnded adds ended ones (not for a worker's session). first: default 20, max 200.
appRef String!
worker String
includeEnded Boolean
first Int
after String
deliveryBatches DeliveryBatchPage! #2017 (S1) — the ready-to-deliver batches of the workers registered on the calling host (hrn:node:hadronmemory.com:specs:cor:agt:080:22, :26). An own live session reads only its bound worker. A host App key needs attention:deliver AND host:operate; the host is the key's, the request names none, and a worker not on that host is absent. The text is written by the server and typed unchanged. Reading moves nothing; acknowledge the batch ids.
appRef String!
workerRefs [String!]
first Int
after String
hostRegistrations [HostRegistration!]! #1709 — the App's host registrations, liveness derived now (hrn:node:hadronmemory.com:specs:cor:agt:070:01). Whoever reads the App's tasks and events, the App's own key included.
appRef String!
hostDesiredState HostDesiredState! #4224 (S3 of #4229) — for each worker one host runs: whether its agent process should be running, and why. A host's sweep reads this once per pass and compares it with what it sees. While the App's hostSetupSource is HOST (the default), a host's workers are the ones its registration lists (hrn:node:hadronmemory.com:specs:cor:agt:070:01), live or lapsed, with the family and worktrees it registered. While it is SERVER (#4248), they are the platform's assignments to that host (hostSetup, #4222), a retired worker's excluded, each with the assignment's family and its one workdir; a host with an assignment but no registration is found. Rows are ordered by worker name. Readers: whoever reads the App's tasks and events (hrn:node:hadronmemory.com:specs:cor:agt:050:21), the App's own key included. A key that holds or ever held host:operate reads its own live host only (hrn:node:hadronmemory.com:specs:cor:agt:070:04); any other hostId answers HOST_NOT_FOUND, exactly as a host the App does not have. A host key's read is a recorded use (hrn:node:hadronmemory.com:specs:cor:agt:070:07). Reads only: nothing is started, stopped or changed.
appRef String!
hostId String!
hostSweepRuns [HostSweepRun!]! #4233 (S10 of #4229) — the recorded runs of one host's sweep, newest first: when each ran, its mode, the counts planned, applied, skipped and failed, and up to 50 per-worker lines with reason codes. Read by whoever reads the App's tasks and events (a participant, the App's own key) and by a host key for ITS OWN host only: another host answers HOST_NOT_FOUND, exactly as a host the App does not have. limit is 1 to 100 (default 20). Reads only.
appRef String!
hostId String!
limit Int
hostSetup HostSetup! #4222 — what the platform says the App's hosts run (hrn:node:hadronmemory.com:specs:cor:agt:070:01, the change Proposed): the hostSetupSource switch and the assignments in effect, of one host when hostId is given. Whoever reads the App's tasks and events, the App's own key included. A host key (an App key holding host:operate) reads only its own host's rows: without hostId it gets them, and a hostId naming another host answers exactly like a host with no assignments (hrn:node:hadronmemory.com:specs:cor:agt:070:04). A key whose host:operate was revoked is refused FORBIDDEN whatever it passes. Each host-key read is recorded (hrn:node:hadronmemory.com:specs:cor:agt:070:07).
appRef String!
hostId String
contextReset ContextReset! #3273 (hrn:node:hadronmemory.com:specs:cor:agt:050:27, hrn:node:hadronmemory.com:specs:cor:agt:070:04): the current state of one context reset whose operation this App key's host collected, ended resets included. The host-key gate runs first, as for the protocol steps: HOST_KEY_REQUIRED (not an App key), APP_NOT_FOUND (not the key's live App), APP_KEY_SCOPE_REQUIRED (no live host scope), APP_KEY_SESSION_BOUND (session carried). Then CONTEXT_RESET_NOT_FOUND for malformed/unknown reset id, another App/host, or a missing operation, all with identical message and extensions and no echoed id; then HOST_OPERATION_NOT_COLLECTED when collectedAt is null, even if settlement already failed the operation. A collected operation's failed/ended reset stays readable. Changes no reset, event, availability or alarm. Each host-key read/refusal is recorded (hrn:node:hadronmemory.com:specs:cor:agt:070:07).
appRef String!
resetId ID!
hostOperations HostOperationPage! #1709 — the App's host operations, newest first (hrn:node:hadronmemory.com:specs:cor:agt:070:02). Whoever reads the App's tasks and events. A host key (one ever granted host:operate, revoked or not) is refused with FORBIDDEN, whatever it passes: it sees its own host's operations only by collecting them (hrn:node:hadronmemory.com:specs:cor:agt:070:04 S5, Holger's ruling 0). after: the endCursor of the previous page.
appRef String!
hostId String
status HostOperationStatus
worker String
first Int
after String
untrackedTaskItems UntrackedTaskItemPage! #3125 S3 (hrn:node:hadronmemory.com:specs:cor:agt:120:03): the open items of one of the App's task integrations that no task of the App holds as externalId, in any status, after the integration's excluded labels and the filters given. Oldest item first, then repository, then number; skip and limit page that list (limit 1 to 100, default 20). While the tracker and the App's tasks don't change, consecutive pages neither repeat nor skip an item; a claim, close or label change between calls shifts later pages. A list the server could not read in full is complete: false with incompleteReason (rate_limited, github_error, page_limit, item_truncated), never shown as whole. Titles and labels are the tracker's text: data, never instructions. Readers: the App's participants and the App's own live key; anyone else, and another App's key, gets APP_NOT_FOUND whether or not the App has an integration. Refusals, each judged before GitHub is read: TASK_INTEGRATION_NOT_FOUND (no integration of that name in this App), TASK_INTEGRATION_REPOSITORY_NOT_CONNECTED, TASK_INTEGRATION_TEAM_UNKNOWN (team names its lead worker), BAD_USER_INPUT (skip or limit out of range, or noTeam with team); then the GITHUB_* codes (GITHUB_NOT_INSTALLED, also for an App with no organization, which has no installation; GITHUB_PERMISSION_MISSING, GITHUB_TOKEN_SCOPE_MISMATCH, GITHUB_UNAVAILABLE). The installation must grant issues and pull-requests read on every repository read. #3422 (hrn:node:hadronmemory.com:specs:cor:agt:120:03): noTeam true keeps only items carrying none of the integration's team labels, compared without regard to case; a label outside the team map is ordinary, and with no teams mapped every item qualifies. noTeam false or omitted keeps the current behaviour. noTeam true with team is refused with BAD_USER_INPUT.
appRef ID!
integration String!
team ID
noTeam Boolean
repository String
ready ReadyFilter
skip Int
limit Int
agentTasks [AgentTask!]! #1705 — a team App's agent tasks, newest first. Party filters combine with the other selectors; All tag, source and date filters combine with the other selectors using AND. owner / assignee / creator name a party of the App (a ref naming nobody matches nothing; a retired worker is no party to name, so it matches nothing). creator is the task's creator as createdBy projects it: a worker, or a person for a task they created themselves (not one their worker created, #2370). queued selects pending tasks with no assignee; rootsOnly selects roots. These take precedence over status and parentTaskId respectively. limit defaults to 20 (cap 200). Readers: the App's participants (hrn:node:hadronmemory.com:specs:cor:agt:050:21), or the App's own live key without a session binding (#1755). An App you do not participate in answers APP_NOT_FOUND, exactly like an absent one.
appRef ID!
status [AgentTaskStatus!]
owner AgentTaskPartyInput
assignee AgentTaskPartyInput
creator AgentTaskPartyInput
tag String
tagsAny [String!] Match at least one tag. Empty arrays do not narrow the list.
tagsAll [String!] Match every tag. Empty arrays do not narrow the list.
source String Exact opaque source value, without interpretation or prefix matching.
externalId String #3125 S2, #4217: the tasks with exactly this externalId (compared as written, 1 to 512 characters, else BAD_USER_INPUT): at most one ACTIVE task (backlog, pending or started) holds it, and any number of finished or cancelled tasks that held it before it. Newest first, so a caller that wants the live one picks the active one. Runs inside the App read gate, so it only finds this App's tasks.
externalIds [String!] #4084 (hrn:node:hadronmemory.com:specs:cor:agt:120:02): the tasks holding any of these external ids, each compared exactly as written. 1 to 100 ids; each entry passes the externalId check (1 to 512 characters, no unpaired surrogate), and ONE bad entry refuses the whole list with BAD_USER_INPUT naming its position (externalIds[i]), never its text; an empty list is BAD_USER_INPUT, never "no narrowing". At most one ACTIVE task holds an id, but finished and cancelled tasks keep it (#4217, hrn:node:hadronmemory.com:specs:cor:agt:120:02, 2026-11-14), so an id can match several tasks: with limit omitted — and offset omitted or 0 — the page is every task holding any of the ids, up to the list cap (200); an explicit limit or offset windows the batch like any list. An id no task of this App holds matches nothing. Runs inside the App read gate (hrn:node:hadronmemory.com:specs:cor:agt:050:21), so another App's task with the same id never appears. ANDed with every other filter, externalId included.
reference AgentTaskReferenceFilter #2649: tasks carrying a reference with exactly this target, and this kind when given; the label is ignored. Runs inside the App read gate.
unresolvedFindings Boolean #2663: true narrows to finished tasks with at least one undisposed finding; false/omitted do not narrow. Existing App read scope, before paging (hrn:node:hadronmemory.com:specs:cor:agt:050:30).
text String Case-insensitive substring of the title or description, 1 to 200 characters after trimming (else BAD_USER_INPUT). Percent, underscore and backslash match literally. ANDed with every other filter.
overdue Boolean True: overdue on the server clock (the database clock). Two arms: a pending task, not started, whose start-by has passed; or a pending or started task whose finish-by has passed and which has not ended. An ended (finished or cancelled) task and a backlog task are never overdue, and neither is a task with neither time. Blocking is ignored. False: all other tasks. Not an alarm: listing raises nothing.
createdAfter DateTime Inclusive creation-time lower bound.
createdBefore DateTime Inclusive creation-time upper bound.
startedAfter DateTime Inclusive start-time lower bound; tasks with no start time never match.
startedBefore DateTime Inclusive start-time upper bound; tasks with no start time never match.
finishedAfter DateTime Inclusive finish-time lower bound; tasks with no finish time never match.
finishedBefore DateTime Inclusive finish-time upper bound; tasks with no finish time never match.
parentTaskId ID
rootsOnly Boolean
queued Boolean
matchFailed Boolean True: only single-shot match failures; false: unmarked tasks. Does not change who may read.
limit Int
offset Int
agentTaskTree [AgentTask!] #1705 — a task and every task below it, the root first, then by depth and creation. Null when the root is missing or unreadable. Bounded at 1000 rows.
root ID!
agentTeamEvents [AgentTeamEvent!]! #1705 — a team App's event stream (hrn:node:hadronmemory.com:specs:cor:agt:050:11). #4098: oldest-first follows the writing transaction, then (createdAt, id) within it. Only transactions below the snapshot xmin are served: a poll can lag while an older transaction is open, but late commits and later writes with older caller timestamps cannot fall behind a served forward cursor. after remains the id of the last event read, not an opaque token. since is a coarse time filter (strictly after), not a continuation. limit defaults to 20 (cap 200). newestFirst/before retain descending (createdAt, id) history order with the same gate, filters and paging; they are not a forward continuation. task.warning, task.edited and task.properties-changed are passive history (never wake, suppress a wake or count as activity); payload is {code}, changed field names only, or (task.properties-changed) the size and SHA-256 of the canonical JSON of the old and new properties, never their content.
appRef ID!
since DateTime
after ID The id of the last event read: the page continues strictly after it. An id that is not an event of this App is refused BAD_USER_INPUT.
before ID #3933: with newestFirst, the id of the last (oldest) event read; the page continues strictly older than it, by the same (createdAt, id) pair. An id that is not an event of this App is refused BAD_USER_INPUT. Refused without newestFirst.
newestFirst Boolean #3933: true reads history from the NEWEST timestamp by (createdAt, id) descending, with the same gate, filters and paging (default 20, cap 200); continue with before, not after (refused with after). Omitted or false: the commit-safe forward stream.
types [String!]
codePrefix String #3449: literal prefix, intersects nonempty types; app. includes legacy platform events. An empty prefix matches all types; omitted or empty types adds no type filter.
alarmsOnly Boolean
alarmsInEffect Boolean #3934 — only alarms in effect (hrn:node:hadronmemory.com:specs:cor:agt:050:20): unacknowledged and with no recorded escalation end, so escalationEndedAt is null. Implies alarmsOnly. An alarm out of effect is skipped, not hidden: read without this filter to see it. false or omitted adds no filter.
taskId ID
limit Int
agentTeamEventsPage AgentTeamEventsPage! #3933 (hrn:node:hadronmemory.com:specs:cor:api:120:04) — agentTeamEvents with the page's end told: the same arguments, gate, filters, order and paging (except the page-size floor below), returning hasMore and nextCursor so a reader knows whether older (or newer) events remain without another read. For the forward stream, hasMore describes the eligible prefix below the snapshot horizon; keep the cursor and poll again while older transactions remain open. nextCursor is the id of the last event served when more remain, to pass as after (oldest-first) or, with newestFirst, as before; null on the last page, and non-null whenever hasMore is true. The page size has a floor of 1: limit is at least 1 (0 or less reads one event, never an empty page), default 20, cap 200 served and never refused (hrn:node:hadronmemory.com:specs:cor:api:120:04). The legacy agentTeamEvents keeps limit 0 as an empty list.
appRef ID!
since DateTime
after ID
before ID
newestFirst Boolean
types [String!]
codePrefix String
alarmsOnly Boolean
alarmsInEffect Boolean #3934 — as on agentTeamEvents: only alarms in effect (unacknowledged, escalation not stopped); implies alarmsOnly.
taskId ID
limit Int
agentTaskExternalIdChanges AgentTaskExternalIdChangePage! #4084 (hrn:node:hadronmemory.com:specs:cor:agt:120, minimal write-back) — what changed on this App's tasks that carry an external id, for a team's reconcile pass: an assignment (by hand or by the platform), a reassignment, a hand-back, a cancel, a finish and a release of the id. Each change is one team event, read inside the same gate as agentTeamEvents (hrn:node:hadronmemory.com:specs:cor:agt:050:21); anyone else is refused APP_NOT_FOUND. A RELEASED change carries the id the release cleared (its task no longer holds it); a change before the release in this read's own order — the (tx_id, created_at, id) key the page is served by, not wall-clock time — carries that id too, and a change after it in that order (the task then holds none) is left out; every other change carries the id its task holds. Order is commit-safe, oldest first: a change is served only once the transaction that wrote it, and every older one, has ended, so it may appear a moment late but never behind a cursor already served. Pass nextCursor (or the last change's cursor) as after to continue; with after omitted the read starts at the oldest change. after is opaque: a value that is not a cursor of this App is BAD_USER_INPUT. limit defaults to 20 (cap 200, floor 1).
appRef ID!
after String
limit Int
accountUsageAccounts AccountUsageAccounts! #3853 — the usage accounts an App has history for: one entry per label, host and family (hrn:node:hadronmemory.com:specs:cor:agt:140:01) with a valid account-usage snapshot in the App's own team-space memory in the last 14 days, the same history and horizon accountUsageProjection reads (hrn:node:hadronmemory.com:specs:cor:agt:140:05). Readers: as accountUsageProjection (hrn:node:hadronmemory.com:specs:cor:agt:140:03, resting on hrn:node:hadronmemory.com:specs:cor:agt:050:21 and hrn:node:hadronmemory.com:specs:cor:agt:050:23); anyone else is refused APP_NOT_FOUND. At most 50 accounts, the most recently written kept, ordered by label, host and family; complete is false when more exist, or when the bounded search for accounts with valid history stopped short. An App with no history gets an empty list.
appRef ID!
agentTaskStallSchedule AgentTaskStallSchedule! #1706 — an App's effective stall windows (hrn:node:hadronmemory.com:specs:cor:agt:050:14–:17), and (#1763) its host-registration lapse (hrn:node:hadronmemory.com:specs:cor:agt:070:01). Readers: the App's task audience (hrn:node:hadronmemory.com:specs:cor:agt:050:21).
appRef ID!
teamAvailability TeamAvailability! #1706 — every worker and model-family availability record in an App (hrn:node:hadronmemory.com:specs:cor:agt:060:02 / :03), each with whether it is in effect now. Readers: the App's task audience (interim until hrn:node:hadronmemory.com:specs:cor:agt:060:02's read question is ruled).
appRef ID!
teamRoster TeamRoster! #1707 — every worker's derived state in an App (plan design:agent-tasks §7.4), computed server-side so the CLI and portal render one answer. Plan- derived, not a spec (hrn:node:hadronmemory.com:specs:cor:agt:050 leaves the roster out of scope). Readers: the App's task audience (hrn:node:hadronmemory.com:specs:cor:agt:050:21). Retired workers are left out.
appRef ID!
teamUtilization TeamUtilization! #3819 slice 1: advisory utilization in the roster audience (hrn:node:hadronmemory.com:specs:cor:agt:050:21). Window defaults to 24h, range 1–168; tier is high/mid/low. Failed-match saturation and alarms await their historical provider.
appRef ID!
family String
tier String
role String
windowHours Int
accountUsageProjection AccountUsageProjection! #3820 — the token-burn projection of one subscription account in an App: the 5-hour and 7-day windows' use at their reset as a range, from the burn over the last 1h, 6h and 24h of history, with an optional what-if (add workers, or move one to another account). The history is the account-usage objects in the App's own team-space memory. Readers: as the team's tasks and events are read (hrn:node:hadronmemory.com:specs:cor:agt:140:03, which rests on hrn:node:hadronmemory.com:specs:cor:agt:050:21 and hrn:node:hadronmemory.com:specs:cor:agt:050:23): the App's participants and its own key; anyone else is refused APP_NOT_FOUND. ADVISORY ONLY: the answer never authorizes, refuses or moves anything. An account with no history, or only history older than 60 minutes, is UNKNOWN; under 5% used, or fewer than 3 snapshots spanning an hour, is INSUFFICIENT_DATA and gives no run-out time.
appRef ID!
account String!
host String
family String
whatIf AccountUsageWhatIfInput
reviewQualityReport ReviewQualityReport! #4281 — an App's review quality measures for one calendar month, one row per reviewer model family and model (hrn:node:hadronmemory.com:specs:cor:agt:130:06). month is YYYY-MM, a UTC calendar month; anything else is BAD_USER_INPUT. A review is one finished review-seat task carrying at least one verdict; its latest verdict (hrn:node:hadronmemory.com:specs:cor:agt:130:02) decides its row and its month, and its findings are the seat task's result findings with their latest dispositions (hrn:node:hadronmemory.com:specs:cor:agt:050:30). Findings and dispositions recorded after the month still count in it, so the answer for a past month can change: asOf says when it was worked out. Readers: as the App's tasks and events are read (hrn:node:hadronmemory.com:specs:cor:agt:050:21 and hrn:node:hadronmemory.com:specs:cor:agt:050:23): the App's participants and its own key; anyone else is refused APP_NOT_FOUND. Descriptive only: never an input to readiness or matching (hrn:node:hadronmemory.com:specs:cor:agt:130:03).
appRef ID!
month String!
teamComposition TeamComposition! #2061 — direct-report lanes from the same roster projection and read gate as teamRoster. One bounded RepeatableRead snapshot per call; no hierarchy rollups or role exclusions.
appRef ID!
registerRoleCandidates RegisterRoleCandidatePage! Experimental register role picker: all readable workers tied at the nearest task depth, paged. Never assigns or routes.
appRef ID!
code String!
limit Int
offset Int
registerRolePick RegisterRolePick! Experimental: the routed pick for a register code: the named worker, else one role holder (matcher least-recently-assigned), else one coordinator-role holder, else the App's managers (shown only to a manager). Empty when nothing matches. Never assigns or delivers.
appRef ID!
code String!
workerRef ID
actionRegisterIndex ActionRegisterIndexPage! #3287 — an App's action-register index, computed at read: every code the App's Team Agent's chain maps, one row per code in code order, with its task loc resolved through the asking Agent's chain (hrn:node:hadronmemory.com:specs:cor:agt:110:03, hrn:node:hadronmemory.com:specs:cor:agt:110:04 Relationships; rulings 0101 A and 0102 A: no stored edge, one server field). Writes nothing and caches nothing. Entries: the nearest register:<code> per code on the Team Agent's chain (its own system memory first, then its bases); a child's entry hides its base's, the App's install memory is never searched, and a nearest malformed entry is UNMAPPED (no farther entry replaces it). Tasks: each entry's taskLoc resolves nearest-first through the asking Agent's chain; a nearest node that isn't runnable is UNRESOLVED (no farther task is used). States: MAPPED (taskUrn set), UNRESOLVED (taskLoc set, taskUrn null), UNMAPPED (code only). The asking Agent (ruling 0106 A): agentRef, else the caller's own Agent (a worker session or an Agent run). agentRef must name an Agent the caller can read that is installed in this App or is a cast worker's Agent; any other ref (unknown, unreadable, outside the App, readable only through another tenant) is refused AGENT_NOT_FOUND identically, never resolved through another Agent. The implicit Agent must also be installed or be a live cast worker's Agent in this App (ruling 0120 A, hrn:node:hadronmemory.com:specs:cor:agt:110:03); otherwise AGENT_NOT_FOUND carries its own Agent URN. A caller with no Agent and no agentRef is refused BAD_USER_INPUT. Read as the caller, all or nothing (ruling 0107 A): unless the caller can read every system memory on the Team Agent's chain and on the asking Agent's chain, through the base, the answer is the empty page an App with no single Team Agent gets (ruling 0060). Filters: taskLoc keeps the codes whose entry names that loc, code keeps one code; a filter naming nothing gives the same empty page. Paged (hrn:node:hadronmemory.com:specs:cor:api:120:04): limit defaults to 20, capped at 200, 0 is count-only; total and hasMore count after the gate and the filters. An unknown, foreign or non-participant App is refused APP_NOT_FOUND identically.
appRef ID!
agentRef ID
taskLoc String
code String
limit Int
offset Int
teamSpecSchema String! Declarative team JSON Schema (2020-12). apiVersion is the full identifier hadron.dev/team/v1alpha1; HTTP discovery uses /schemas/team/v1alpha1.json. CLIENT_INPUT additionally permits file parts for clients to inline; the server accepts SERVER only.
apiVersion String!
form TeamSpecForm
resolveUrn UrnResolution Resolve a fully-qualified, `hrn::`-prefixed Hadron URN (legacy `urn:` scheme also accepted) to the ids needed to reach its canonical page. Missing or inaccessible targets normally return null. Ambiguous legacy node references can instead refuse with extensions.code AmbiguousLegacyUrnError. Access is checked by kind: memory records use the memory-record read gate; nodes use the readable-memory set; organizations require membership (or platform administration); agents admit public visibility or owner/org access; Apps admit owner/org access; workers use the shared worker-read gate. Users resolve for themselves, a platform administrator, or a caller who shares an organization with them. App runs require org access, and node revisions use their captured memory (falling back to the current node's memory); a retracted comment's revision history resolves only for memory managers. Under impersonation only the support session's shared organization admits organizations, Apps, non-public Agents, workers and App runs, and a user-owned App or non-public Agent is not visible; a PUBLIC Agent still resolves. A retired worker still resolves. The kinds above are checked by kind, not an exhaustive promise. Dedicated queries can have different refusal shapes. The type prefix is the dispatch key; an untyped root:slug is ambiguous across kinds and returns null. The optional #data fragment is supported only for nodes and App runs.
urn String!
effectiveAccess EffectiveAccess! issue #323: resolve the effective access a single user has to a single resource, with the grants that confer it. The authoritative backing for the 'hadron access check <user> <resource>' audit command — one resolver that reuses the server's authorization rules instead of re-deriving them client-side. 'user' (the subject) accepts a User ID or a hrn:user:<handle> URN (spec cor:urn:010:01). 'resource' is dispatched on URN type the same way resolveUrn dispatches: a memory, node, app, agent, org, or user MUST be a fully-qualified hrn:<type>: URN (a bare id is ambiguous across those kinds). A bare id with no scheme prefix is treated as an AiServiceConfig id — the only URN-less resource kind. Self-audits are allowed subject to resource visibility. Cross-subject audits require platform administration, resource-org ADMIN/OWNER authority, or the applicable user-owner authority (including a strict-owner memory's principal). A forbidden audit is FORBIDDEN. Before that caller gate, unreadable memory/node/Agent resources are concealed as NOT_FOUND; self-audits conceal any unreadable resource the same way. Impersonation is restricted to the shared org and refuses identity-scoped or other-org resources with FORBIDDEN. Once admitted, a subject with no access is a SUCCESS with an empty grants list (all capabilities false, role null). Unknown subjects and unresolvable resource refs are NOT_FOUND. This query's supported resource kinds are not every resolveUrn kind.
user ID!
resource ID!
node Node The uniform single-node read (#473) — subsumes the former nodeById(id:) and node(loc:, memory:) split. 'ref' accepts, in dispatch order: 1. a primary key (the unambiguous read — the old nodeById), 2. a fully-qualified node URN (`hrn:node:::`, legacy `urn:` scheme accepted), 3. a bare loc — scoped by 'memoryRef' (an ID or URN) when given; unscoped, it resolves across every readable memory and a cross-memory loc collision is REJECTED with extensions.code AMBIGUOUS_NODE_LOC (listing the candidate memoryIds) rather than silently returning one (#335). An unprefixed 3+-segment ref whose first two segments name a live memory is treated as form 2 (a full URN); pass 'memoryRef' to force loc interpretation. raw: true selects stored content without include or variable resolution. Soft-deleted nodes do not resolve. Access uses the caller's readable-memory set. A denied or missing node returns null; an explicit memoryRef that is missing or unreadable raises MEMORY_NOT_FOUND. When addressed in a system memory by memoryRef or a full node URN, a loc with no local node may read through to an eligible inherited node under its own address; overrides and boot prompts are excluded. An unscoped bare loc does not search inheritance.
ref ID!
memoryRef ID
raw Boolean
nodeExport NodeExportResult! Render one node to a portable, self-contained file (spec cor:api). full: true (default) returns the CANONICAL form — byte-identical to "hadron node export <urn>", all sections, round-trippable via "hadron node import". Requires MD or JSON; sections is ignored. full: false returns a PRESENTATION render of the selected sections (default: all); not guaranteed round-trippable. Auth: same node-read gate as node(ref:). (HTML/PDF + asUrl delivery land later; the result shape is forward-compatible.)
id ID!
format NodeExportFormat
full Boolean
sections [NodeExportSection!]
findNodes FindNodesResult! Unified node search (cor:api:090) — the single node list + retrieval surface (it replaced the removed `nodes` filter/list and `nodeSearch` rank queries in PR3). Omit `query` for a filtered list in deterministic order (subsumes `nodes`); pass `query` to rank by `mode` (keyword | vector | hybrid | regex). Lexical modes honor boolean operators (`(a OR b) AND c`, quoted phrases, NOT/-) — operator words are UPPERCASE-ONLY, so natural phrases like 'not sure' search literally — and `fields` as a ranking weight-mask. Malformed boolean syntax (unmatched parenthesis, unterminated quote) DEGRADES to a literal phrase search flagged `degraded: 'literal_fallback'` instead of erroring; only mode: regex fails loudly on bad syntax. `filter` is the structured, AND-combined filter context (SYSTEM memory class excluded by default; explicit wins). Returns a scored-hit envelope. Access-scoped identically to the per-kind node queries. orgId (optional) narrows the accessible scope to a single organization the caller is a member of; a non-member orgId returns an empty envelope (total 0, no existence disclosure). Combined with filter.isRunnable: true this is the canonical "the caller's runnable task nodes in one org" query (there is no separate myTasks surface — a task is simply an isRunnable node).
query String
mode FindNodesMode
filter NodeFilter
fields [NodeField!]
sort NodeSort
sortProperty NodePropertySort #719 — order by a properties/data JSON path; overrides sort when present.
expand Int
granularity SearchGranularity
orgId ID
limit Int #437 — primary page size, default 20 (also null), clamped to 1–200. Expansion neighbors are additional. hrn:node:hadronmemory.com:specs:cor:api:090
offset Int #437 — page offset, default 0 (also null); negative values become 0. No offset ceiling. #2991: in vector and hybrid modes, offset pages are not snapshot-stable while the memory's vector index is filling (an embedding landing between reads can repeat one hit and skip another); callers who need complete, duplicate-free paging use mode: keyword on one memory, ordered score DESC then loc (unique within a memory; across memories, hits with equal score and loc have no defined order). hrn:node:hadronmemory.com:specs:cor:api:090
minScore Float Optional absolute relevance floor (cor:api:090 / #497): drop ranked hits whose score is below this value. Scores are NOT comparable across modes, so the meaningful scale differs per mode (keyword ts_rank is roughly 0..a-few; vector cosine similarity is 0..1; hybrid is a small RRF fraction) — pick a floor for the mode in use. Ignored on the no-query browse list (unscored) and never trims expand-neighbours. A floor returns fewer hits, never weaker ones.
scope String Spec 049 (D-2026-09-13-002): search under a named scope — a scope id, a bare scope name (needs appRef), 'app' (the App's attached memories; needs appRef), or 'global' (the active organization's view — orgId, or your single membership). The scope's memories are intersected with your access (a lens never grants; the rest is disclosed as scope.droppedCount) and filter.memoryIds narrows WITHIN it. Omitted: the pre-049 behaviour — your accessible set, optionally narrowed by orgId.
appRef ID Spec 049: the App context for a bare scope name or for scope: 'app' (ID or URN).
object JSON #745 — read one object by its id (the object store's flat projection of a node). Returns a JSON object { id, type, ...fields } or null if not found/inaccessible. The object store is the legible sugar surface over structured storage (an object IS a node); see createObject / findObjects.
ref ID!
findObjects ObjectList! #745 — query a collection. Returns objects of the given type (the collection / node objectType) in the memory, projected flat. 'match' is an equality shorthand ({ field: value }) desugared to a where predicate with each field's cast inferred from the memory schema; 'where' is the full #719 predicate (ANDed with match); 'sort' is a single-field shorthand desugared to a property-path sort.
memoryRef String! Memory ID or fully-qualified URN (hrn:memory:...) — relative refs are rejected (spec 022).
type String!
match JSON Equality shorthand: { field: value, ... } becomes an AND of eq predicates (cast inferred from the schema).
where JSON Full #719 structured predicate over the object's fields (ANDed with match).
sort JSON Single-field sort: a map of one field to the direction string 'asc' or 'desc', e.g. { fundingUsd: 'desc' }.
limit Int
offset Int
globalSearch GlobalSearchResult! Cross-entity global search across organizations, memories, nodes, agents, apps, AiServiceConfigs, and users — one ranked, flat list of hits. By default the query shape is smart-sniffed: a PK-shaped input does an exact id lookup, a URN-shaped input matches URNs, anything else matches name + URN. Pass `fields` to force specific fields (overrides the sniff) and `entityTypes` to restrict the kinds searched. Every hit is access-scoped to the caller exactly as the per-kind queries are. Distinct from `findNodes`, which is the node-only, vector-aware retrieval surface. orgId (optional) narrows the org-anchored slices to a single organization: node/memory hits are confined to that org's memories and organization / agent / app / aiServiceConfig hits to that org. (The user slice is NOT org-scoped — users aren't org-owned; they stay gated by the caller's user-visibility as usual.) Omit for the cross-org union (default). A caller who is not a member of orgId gets an empty page (total: 0) — no org-existence disclosure; membership-gated for everyone, no admin bypass. Paged in the repo standard idiom: limit (default 20, capped 200) + offset (default 0), with total in the envelope. NOTE: total is the ranked-match count WITHIN the per-entity candidate bound (a fixed cap per entity type), not an unbounded COUNT — deep paging past that bound is not surfaced. See GlobalSearchResult.total.
query String!
entityTypes [SearchEntityType!]
fields [SearchField!]
orgId ID
limit Int
offset Int
scope String Spec 049 (D-2026-09-13-002): run the memory + node slices under a named scope — a scope id, a bare name (needs appRef), 'app' (needs appRef), or 'global' (orgId, or your single membership). See findNodes.scope; the result's scope field discloses what applied.
appRef ID Spec 049: the App context for a bare scope name or scope: 'app' (ID or URN).
edge Edge The uniform single-edge read (#473) — edges are first-class, loc-addressed peers of nodes (spec 037). 'ref' accepts a primary key or a fully-qualified edge URN (`hrn:edge:::`; the edge's memory is its SOURCE node's memory). Access: the edge's memory must be in the caller's readable set; denied and missing are both null.
ref ID!
edges EdgesPage! Uniform paginated edge list (#473). Scope: edges whose (denormalized, source-side) memory the caller can read, AND-narrowed by the filter. orgId follows cor:api:100:01 (member -> scope, non-member -> empty page, no disclosure, no admin bypass). Deterministic loc-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only.
filter EdgeFilter
orgId ID
limit Int
offset Int
nodeBatch NodeBatchResult! Batch read (spec cor:api:040) — the full node projection (select any Node fields, including content + edges) for MANY nodes in one call, eliminating the N+1 of one node(ref:) per node (e.g. 'spec lint --all'). Provide EITHER 'refs' (explicit set, returned in input order) OR 'memory' + 'locPrefix' (subtree, loc order) — not both. Each entry of 'refs' is a primary key OR a fully-qualified node URN (cor:api:140), so a URN-holding caller batches in ONE call instead of resolving each ref first. The split on a bad ref is by KIND, not by luck: a ref whose SHAPE is wrong errors the call — unqualified / relative (UrnNotQualifiedError) or a URN of the wrong entity type, e.g. 'hrn:mem:...' (BAD_USER_INPUT) — while a well-formed ref that names nothing the caller may read comes back in 'unavailable'. A caller mistake stays loud instead of hiding among denials. Per-node access is applied independently AFTER resolution: denied or missing refs come back in 'unavailable' and never fail the call. Bounded by hard caps — over the node-count cap throws BAD_USER_INPUT; over the response-size cap returns a partial result with 'truncated: true' and the dropped refs in 'omitted' (never a silent short read). Node content is returned raw — Mustache templates are NOT compiled (unlike the single-node 'node' read), since this is a bulk source read for lint / audit / migration and compiling per node would re-introduce the N+1 it eliminates. Requested edge fields share a 2000-row budget for this batch result; exceeding it returns BAD_USER_INPUT. Read large edge sets through the paged edges query. Unselected edges and endpoint bodies are not prefetched by the batch read.
refs [ID!]
memory ID
locPrefix String
skillPlan SkillPlan! #1177 section 3 — the SKILL SEAM: the server judges, the client does I/O. One surface serving skill lint, skill status and skill export. The client sends what it can see of each file on disk; the server returns a drift CLASS and the lint findings per declared node, plus the rendered body for anything the client is to write. A QUERY, not a mutation, and that is the contract. Nothing here writes to a node — publishing is one-way, and the only writer in the feature is the client's own filesystem. So status and lint cannot write by construction rather than by promise. The client cannot name a drift class: the vocabulary is the server's, so it cannot drift between clients. A node failing lint is never given a rendered body, so a client cannot write a file the server judged broken.
input SkillPlanInput!
selectedSkillFilePlan SkillPlan! Selected individual skill files only. Plugin bundles cannot use node selectors.
input SelectedSkillFilePlanInput!
nodeUsage ⚠️ [UsageEvent!]! DEPRECATED: use usageEvents(loc: <loc>). Carried for source-compat; there are no known callers (checked across portal / CLI / docs at #802). Usage events for a node loc, most recent first. The migration is a rename, not a rewrite — usageEvents' loc argument is the SAME verbatim exact nodeLoc match under the same gate, so nodeUsage(loc: "x", limit: n) becomes usageEvents(loc: "x", limit: n) with identical results and identical access scoping: nodeUsage(loc: 'cor:acl:010:01', limit: 20) usageEvents(loc: 'cor:acl:010:01', limit: 20) Do NOT migrate to usageEvents(nodeId: <loc>): nodeId is shape-classified, and a hierarchical loc with 3+ colon-separated segments (like the spec citation above) qualifies as node-URN shape and routes to ref resolution instead — NODE_NOT_FOUND, or another node's events (PR-986 review). The loc argument exists precisely so the migration needs no shape caveats. usageEvents is a strict superset: nodeId accepts a PK or a fully-qualified node URN (memory-precise — a bare loc cannot disambiguate the same loc in two memories), plus type filtering, memoryId scoping and offset paging. It is also the surface that gets extended; nodeUsage will not grow arguments. Access control is identical and unchanged (#802) — see usageEvents below. Deprecated for redundancy, NOT because this field is unsafe.

⚠️ DEPRECATED

Use usageEvents(loc: <loc>) — identical exact-match loc semantics and access scoping, plus PK/URN refs via nodeId, type filtering, memoryId scoping and paging (#802).
loc String!
limit Int
usageEvents [UsageEvent!]! Usage events (most recent first), optionally filtered by type, memoryId, nodeId, or time. since is inclusive and until is exclusive: since <= createdAt < until. Bounds must be ISO date-times with Z or an explicit offset. Either bound may be omitted; invalid bounds or since >= until are BAD_USER_INPUT. Windowing does not change scope (hrn:node:hadronmemory.com:specs:cor:acl:090:01). Scope (#2817, hrn:node:hadronmemory.com:specs:cor:acl:090:01): naming NO resource (no memoryId, nodeId or loc) reads the caller's OWN activity, the events attributed to the calling user in any memory or none. An App key has no own activity and gets an empty list, not an error. Naming a resource reads every principal's events there, gated on READ access to the memory (#250: org membership / subscriptions / public / owned personal+private per spec 034; ADMIN/OWNER see all EXCEPT another user's personal/private memories and, per spec 047, another user's user-owned memories). A memoryId the caller can't read answers MEMORY_NOT_FOUND exactly as a missing one (hrn:node:hadronmemory.com:specs:cor:api:140:03). An empty resource scope never falls back to own activity. An App key's resource read discloses volumes only: userId, sessionId, organizationId and actionArgs are null, and appId is null unless it is the key's own App. limit pages as usageEventsPage does: default 20, at most 200 (hrn:node:hadronmemory.com:specs:cor:api:120:04). memoryId is a memory identifier — accepts the memory's ID or URN. Results are scoped on the denormalized UsageEvent.memoryId column (#796), so an event stays attributed to its memory after its node is deleted. nodeId is a node token accepting a PK, a fully-qualified URN, or a bare loc (no memoryId needed): - PK / URN → resolved to a single node; scoped via its exact nodeId FK (memory-precise). - bare loc → exact nodeLoc match, bounded to readable memories; not existence-checked. Shape-classified: a loc with 3+ colon-separated segments qualifies as node-URN shape and takes the PK/URN branch instead — use loc for those. (This used to read "like nodeUsage but access-scoped" — a comment that named an ungated sibling without anyone following the pointer back. nodeUsage was gated in #802 and deprecated as redundant in the same issue.) loc — the VERBATIM exact nodeLoc filter (never shape-sniffed, so every loc works, hierarchical spec citations included), bounded to readable memories; not existence-checked. The migration target for the deprecated nodeUsage(loc:) above — same match, same gate (PR-986 review, Codex P2). Mutually exclusive with nodeId (BAD_USER_INPUT when both are passed). appKey (#2944, hrn:node:hadronmemory.com:specs:cor:acl:090:01 "Filtering by App key") — an App key's id. Keeps only the events made by requests that key authenticated; events made without a key, and every event recorded before keys were attributed, are never returned. Open to whoever manages the key's App (hrn:node:hadronmemory.com:specs:cor:dmo:050:12, acting as themselves) and to the key itself; anyone else gets APP_KEY_NOT_FOUND, exactly as for a key that does not exist, before any memory or node is resolved. A manager sees the key's events only in memories the manager can read (no resource named: every such memory; a named memory still needs READ). The key, naming no resource, sees its own events in the memories it can read now, plus its events attributed to no memory (ruling 0254); naming a node, loc or memory, it sees only its own events there, in memories it can read. It composes with the window, type and resource filters. Rows stay volume-only as above.
type String
memoryId ID
nodeId ID
loc String
since DateTime
until DateTime
appKey ID
limit Int
offset Int
usageEventsPage UsageEventPage! #2212 - `usageEvents` as a page: the same principal gate, the same loc/nodeId rules and the same two scopes (own activity when no resource is named, #2817), ordered newest first with an id tiebreak, with the windowed total. since is inclusive and until is exclusive: since <= createdAt < until. Bounds must be ISO date-times with Z or an explicit offset. Either bound may be omitted; invalid bounds or since >= until are BAD_USER_INPUT. hrn:node:hadronmemory.com:specs:cor:acl:090:01; paging: hrn:node:hadronmemory.com:specs:cor:api:120:04. Sizes as `tickersPage`. appKey filters by an App key exactly as on usageEvents (#2944), and the total counts the filtered rows.
type String
memoryId ID
nodeId ID
loc String
since DateTime
until DateTime
appKey ID
limit Int
offset Int
nodeRevisions [NodeRevision!]! Revision history for a node, most recent first. Accepts the node's ID or URN. Access-gated on the node's memory: a node whose memory the caller can't read returns an empty list (no existence disclosure).
nodeRef ID!
limit Int
nodeEdgeRemovals [NodeEdgeRemoval!]! #2517 — the audit entries a HARD delete left on this node when it removed edges the node held to the deleted target, newest first (default 20). A separate record, never a NodeRevision: revisions stay snapshots of the node's own fields. A soft delete keeps its edges and records nothing. Same read gate as nodeRevisions; a node you cannot read returns an empty list. hrn:node:hadronmemory.com:specs:cor:dmo:010:04
nodeRef ID!
limit Int
nodeRevisionsPage NodeRevisionPage! #2212 - `nodeRevisions` as a page: the same access gate (a miss or an unreadable node is an empty page), with the snapshot-memory gate applied before counting, so `total` and the pages hold only snapshots you may read and never fall short near the limit. Newest first with an id tiebreak. Sizes as `tickersPage`.
nodeRef ID!
limit Int
offset Int
verifyNode NodeIntegrityCheck! #1591 — the tamper check: recompute the node's approval hash from its current title/abstract/content and compare it with the approval on record. A pure read; an encrypted memory needs its session key (SESSION_EXPIRED otherwise).
nodeRef ID!
signingRequest SigningRequest #1632 — one signing request; null when unknown or when its node is not readable to the caller.
id ID!
grantSigningRequest GrantSigningRequest #3649 slice B (hrn:node:hadronmemory.com:specs:cor:acl:140:07) — one grant signing request; null when unknown or when its grant is not readable to the caller: a bound worker session in its own App, or a person acting as themselves who manages the grant's live, installed App (as appGrants reads it).
id ID!
verifyMemoryNodes MemoryIntegrityReport! #1591 — the tamper check over every live node of a memory (ID or fully-qualified URN).
memoryRef String!
commentThreads CommentThreadPage! #1606 — the discussion on a node (ID or URN), newest thread first. Read-gated on the node's memory; an unreadable or missing node is COMMENT_TARGET_NOT_FOUND.
targetRef ID!
state [CommentThreadState!]
limit Int
offset Int
comment Comment #1606 — one comment by ID or URN; null when missing or unreadable.
ref ID!
decisionLog DecisionLog #1641 — a decision log's settings by ID or URN; null when missing or unreadable.
ref ID!
decision Decision #1641 — one decision by ref (ID or URN), or by code (DU, or a citation DU-1) within logRef. Null when missing or unreadable.
ref ID
code String
logRef ID
decisions DecisionPage! #1641 — the decisions of one log (logRef), or with awaitingMe the OPEN decisions the caller decides across every memory they can read. State is derived for every candidate BEFORE the filters, sort and paging; a list above 5000 candidates refuses (DECISION_LOG_TOO_LARGE_FOR_FILTER).
logRef ID
awaitingMe Boolean
state [DecisionState!]
tier DecisionTier
urgency [DecisionUrgency!]
authorizes Boolean
sort DecisionSort
limit Int
offset Int
verifyDecision DecisionVerification! #1641 — re-render a decision from its payload and check it against its content, data and approval: the findings behind its state.
ref ID!
nodeRevision NodeRevision A single node-revision snapshot by its id (#617 Display). Access-gated on the snapshot's node memory (read): null when the revision does not exist OR the caller cannot read the node's current memory OR the memory the snapshot was captured in (per-snapshot gating mirrors nodeRevisions — a moved node keeps its id, so a snapshot may belong to a memory the caller cannot read). A soft-deleted node is also null (its history drops out of every read surface). Null, never an error, so there is no existence disclosure.
revisionId ID!
memoryUsageSummary [UsageSummaryEntry!]! Aggregated usage counts per node and type for a memory. Accepts the entity's ID or URN.
memoryRef ID!
usageActivity [UsageActivityBucket!]! #796 — read/write activity counts, bucketed by time. Default scope is the caller's OWN events across everything they touched; pass memoryRefs to switch to all users' events attributed to ANY of those memories (#805), each of which requires read access. The result is the UNION as a single read/write series, not a per-memory breakdown; since every event carries exactly one memory, the union equals the sum of the separate scopes with no double-counting. A ref the caller cannot read — or that does not exist — is silently dropped from the union rather than failing the query, so the result never reveals which of the named memories exist. Passing an empty list therefore yields an empty result, NOT the caller's own activity. A malformed ref is still an error. At most 20 refs. Only non-empty buckets are returned — zero-fill the window client-side. Counts only events of type read and write. Window bounds are ISO-8601 strings: from is INCLUSIVE, to is EXCLUSIVE, so adjacent windows tile without double-counting. Defaults to the 7 days ending now; a span longer than 366 days is clamped by moving from forward.
from String Window start, inclusive. Default: to minus 7 days.
to String Window end, exclusive. Default: now.
bucket UsageActivityBucketSize
memoryRefs [ID!] Switch scope to all users of these memories, unioned (each ID or URN; max 20).
timeZone String IANA zone deciding where bucket boundaries fall. Default UTC.
sessions [Session!]! Sessions VISIBLE to the caller, newest first — not only the caller's own. The scope is authorization-derived (`sessionScopeFilter`): a platform ADMIN/OWNER sees sessions in its audience, an App key sees its own App's, and an ordinary user sees those of Apps in any org they belong to **plus** every session of their user-owned Apps and every session attributed to them (these identity-scoped branches do not apply through impersonation). So a client must not present these as "my activity" — many rows may be attributed to other users or Apps. Sessions bound to personal/private memories additionally require that memory's strict owner, with no admin or impersonation override. A pure App key may also read only the session it is itself bound to. Unfiltered, this is also the GENERAL row of every `type`, worker-bound or not (#1034), so it is equally not a list of worker sessions. workerRef (#974): only sessions bound to that Worker (by id), newest first - the 'taken right now' / 'last driven by' read (cor:agt:020:03). That filter is what narrows this to worker sessions.
type String
repo String
customerId String
workerRef String
limit Int
offset Int
sessionsPage SessionPage! #2212 - `sessions` as a page: the same session scope and filters (a blank or unresolvable workerRef is an empty page), newest first with an id tiebreak, with the real total. Sizes as `tickersPage`.
type String
repo String
customerId String
workerRef String
limit Int
offset Int
session Session
id ID!
user User The uniform single-user read (#473). 'ref' accepts a primary key or a `hrn:user:` URN. Resolves for the user themselves, a platform ADMIN/OWNER, or a caller sharing at least one organization with the target (the resolveUrn user gate); anyone else gets null — denied and missing are indistinguishable, preserving #384's anti-enumeration posture. PII fields (name/email) stay gated by the User field resolvers.
ref ID!
users UsersPage! Uniform paginated user list (#473) — replaces the admin-only users list and searchUsers. Platform ADMIN/OWNER: every live user, filter.query optional. Everyone else: filter.query is REQUIRED (blank/omitted -> empty page) and matching is enumeration-safe per cor:acl:070:02 — handle / githubUsername by substring, email by exact match, and name for platform admins or users sharing one of the viewer's active org memberships. Name-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only.
filter UserFilter
limit Int
offset Int
me User Current authenticated user
authContext AuthContext The resolved principal for the credential on THIS request (issue #562). Credential-type-agnostic: works for personal API keys, JWT sessions, and App keys alike — unlike me, which is null for a valid App credential. Returns null when the presented credential does not resolve (identically for revoked / never-existed / malformed — never a token oracle). See the AuthContext type for the full security posture.
authenticationStatus AuthenticationStatus! Whether the credential THIS request presented authenticated (hrn:node:hadronmemory.com:specs:cor:aut:010:05). REFUSED is the identical answer, in status and body for the same operation, for every cause: garbage, expired, wrongly signed, revoked, from an ended sign-in, for a deleted user, or an ended impersonation. Timing is an accepted limit. It takes no argument, so it cannot test a token the caller does not hold. A credential check that could not complete is the ordinary internal error for this field, never REFUSED; every other field answers as before. me and authContext are unchanged (null for a refused credential).
impersonationSession ImpersonationSession One admin-impersonation audit record by id. Resolvable to the session's admin, an org ADMIN/OWNER of its org, or a platform admin; anyone else gets null (denied and missing are indistinguishable).
ref ID!
impersonationSessions ImpersonationSessionList! Uniform paginated admin-impersonation audit list (createdAt-desc). Platform admins may omit orgId (unscoped); everyone else must name an org they are a live ADMIN/OWNER of. filter.activeOnly keeps only currently-live sessions. limit default 20 / cap 200.
orgId String
filter ImpersonationSessionFilter
limit Int
offset Int
organizations OrganizationsPage! Uniform paginated organization list (#473) — replaces organizations + myOrganizations. Scope: the caller's memberships; platform ADMIN/OWNER get every live org (the established admin unscoped reach) unless filter.memberOnly restricts the list to their own memberships (the old myOrganizations view, as a slice-as-filter). Name-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only.
filter OrganizationFilter
limit Int
offset Int
organization Organization Fetch an Organization (org member or platform ADMIN). 'ref' accepts the entity's ID or URN.
ref ID!
publicOrganization PublicOrganization cor:acl:080:02 — the sanitized PUBLIC view of a DISCOVERABLE organization, safe for a non-member. Returns non-null only when the org exposes a public footprint (a PUBLIC memory/agent, or listedOnMarketplace); otherwise null (denied is indistinguishable from not-found — anti-enumeration). Never exposes members, private memories, apps, or credentials. 'ref' accepts the org ID or URN.
ref ID!
marketplaceOrganizations MarketplaceResourcePage! cor:acl:080:04 — browse the marketplace catalogue: resources opted-in via listedOnMarketplace AND publicly accessible. Public (no membership required); sanitized flat refs only (never members / private data / credentials). One paginated query per resource type; ordered by (name, id) for stable paging. - marketplaceOrganizations: listedOnMarketplace orgs. - marketplaceAgents: listed + visibility=PUBLIC agents. - marketplaceMemories: listed + public-readable memories. Drill into an org's public footprint via publicOrganization(ref:).
limit Int
offset Int
marketplaceAgents MarketplaceResourcePage!
limit Int
offset Int
marketplaceMemories MarketplaceResourcePage!
limit Int
offset Int
invitation PublicInvitation Invitation lookup (public to the slug holder). Returns only invite-page display fields; accepting the slug still performs its own authorization.
slug String!
memory Memory Fetch a single Memory (org member, shared-read gate, or platform ADMIN). Missing and unreadable refs both return null without an error, so a caller cannot use this field to test whether a private memory exists. Malformed refs still fail as caller errors, and operational faults still propagate. 'ref' accepts the entity's ID or URN.
ref ID!
installMemory Memory #2044 (hrn:node:hadronmemory.com:specs:cor:agt:040:06) — the App's install memory for an Agent: where the App keeps its customisation of that Agent. Null when the App has not customised it yet (this read creates nothing), and null for anyone the memory's record is not open to: the App's participants, and whoever manages the App.
appRef String!
agentRef String!
memories MemoriesPage! Uniform paginated memory list (#473) — replaces myMemories, publicMemories, and orgSystemMemories. Default scope: the caller's union — (1) their OWN personal/private memories (always; they are user-owned and show in every org context), (2) memories their member orgs own, (3) memories their member orgs subscribe to. Per-user agent memories (userMemoryOfAgentId) are excluded. App-key callers get the union of their installed Agents' memory items. filter.visibility: PUBLIC selects the public marketplace slice instead (every PUBLIC memory — the old publicMemories). filter.memoryClasses restricts to exactly the listed classes; omitted, the noisy agent system class is hidden by default (pass it explicitly to surface system memories, e.g. the old orgSystemMemories = orgId + memoryClasses: [system]). orgId follows cor:api:100:01: member -> the "active organization" view (own personal/private + that org's owned + subscribed memories); non-member -> empty page, no existence disclosure, no admin bypass. Name-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only.
filter MemoryFilter
orgId ID
limit Int
offset Int
dashboardWidgets [DashboardWidget!]! #772 — the caller's placed dashboard widgets, ordered by position. Empty for a non-user (App-key) caller.
dashboardWidgetData [DashboardWidgetData!]! #797 — data for each of the caller's PLACED widgets, in position order, one entry per placement built from its own config. Empty for a non-user caller.
dashboardWidgetPresets [DashboardWidgetPreset!]! #806 — the caller's saved widget configurations, name-ordered (id tiebreak), optionally narrowed to one widget type. Empty for a non-user caller; never another user's presets.
type DashboardWidgetType Return only presets for this widget type. Omit for all of them.
dashboardWidgetPresetsPage DashboardWidgetPresetPage! #2213 — `dashboardWidgetPresets` as a page: the same owner scope and order, with the real total. Empty for a non-user or impersonated caller. Sizes as `tickersPage`.
type DashboardWidgetType Return only presets for this widget type. Omit for all of them.
limit Int
offset Int
connectionFlow ConnectionFlow! Where the connect flow started by startConnection is (#2913, hrn:node:hadronmemory.com:specs:cor:dmo:080:04). Readable only by the user who started it, for one hour from the start; an unknown, expired or another user's flowId gets one refusal (FORBIDDEN), the same for all three. Reading writes nothing.
flowId ID!
exchangeConnections [ExchangeConnection!]! Exchange connections for an org. Accepts the entity's ID or URN.
orgId ID!
exchangeConnectionsPage ExchangeConnectionPage! #2213 — `exchangeConnections` as a page: the same admission (org ADMIN/OWNER, platform admin) and FORBIDDEN refusal, the same rows and order, with the real total. Sizes as `tickersPage`.
orgId ID!
limit Int
offset Int
slackConnection SlackConnection Fetch one Slack connection by id (spec 043). Returns null when the row does not exist OR the caller is not a member of its org — no existence disclosure.
ref ID!
slackConnections SlackConnectionsPage! Uniform paginated Slack-connection list (cor:api:120). Default scope: the caller's member orgs. orgId follows cor:api:100:01 (member -> that org, non-member -> empty page, no disclosure, no admin bypass). Team-name-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only.
orgId ID
limit Int
offset Int
mcpServer McpServer Fetch one registered external MCP server by id. Returns null when the row does not exist OR the caller is not a member of its org — no existence disclosure.
ref ID!
mcpServers McpServersPage! Uniform paginated MCP-server list (cor:api:120). Default scope: the caller's member orgs. orgId follows cor:api:100:01 (member -> that org, non-member -> empty page, no disclosure, no admin bypass). Slug-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only.
orgId ID
limit Int
offset Int
webPolls ⚠️ [WebPoll!]! The organization's active page-monitor watches (#1562): what web_poll_list returns inside a run, for org ADMIN/OWNER outside one. Refused with POLICY_DENIED when the org, caller user or App-in-context policy omits tool.web_poll (no App layer when the context has no App). Jobs with no routing binding in this org are not listed. One page only: default 20, clamp 1–100, use webPollsPage for hasMore and nextCursor.

⚠️ DEPRECATED

One bounded page only; use webPollsPage for hasMore and nextCursor.
orgRef ID!
first Int
webPollsPage WebPollsPage! The same org ADMIN/OWNER and tool.web_poll policy gates as webPolls, before fetching jobs; App policy is read only for the App in the caller context. Jobs without a routing binding in this org are omitted. Default 20, clamp 1–100; authenticated jobId keyset cursor scoped to org. offset is an alternative, never combined with after. total counts all currently admitted watches. hrn:node:hadronmemory.com:specs:cor:api:120:04; hrn:node:hadronmemory.com:specs:cor:api:120:05.
orgRef ID!
first Int
after String
offset Int
mcpServerTools [McpServerTool!] Live tools/list passthrough for one registered server (org member) — what authors browse to pick data.tools entries. Applies the same admissibility filter as run-tool materialization, so what it returns IS what a run can call: a disabled server errors with MCP_SERVER_DISABLED rather than listing uncallable tools. Null when the row does not exist or the caller is not a member of its org; errors with MCP_TOOL_* codes when the conduit or the external server fails.
ref ID!
secret Secret Fetch one secret's inspectable half (never the value). Null when the row does not exist OR the caller is not entitled to its owner scope — no existence disclosure. Entitlement: user -> that user; org -> org member; app -> a member of the App (a person acting as themselves; an App key and an impersonated session get null).
ref ID!
secretEvents SecretEventsPage! The audit events of ONE App secret, newest first, for any member of the App (hrn:node:hadronmemory.com:specs:cor:sec:010:05). A non-member, an App key, a run and an impersonated session get an empty page, the same as a missing secret. Never a value.
ref ID!
limit Int
offset Int
secrets SecretsPage! Paginated secret list for ONE owner scope (the hadron secret ls surface). ownerRef accepts ID or URN (cor:api:140) and defaults to the caller for ownerType user. An unresolvable ref or a non-entitled owner (for an App: anyone who is neither a member nor a manager of it, an App key and an impersonated session) yields an empty page — no disclosure. Name-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only.
ownerType String!
ownerRef ID
limit Int
offset Int
homeAssistantInstance HomeAssistantInstance Fetch one registered Home Assistant instance (org member). Null when the row does not exist OR the caller is not a member of its org — no existence disclosure.
ref ID!
homeAssistantInstances HomeAssistantInstancesPage! Uniform paginated Home Assistant instance list (cor:api:120). Default scope: the caller's member orgs. orgId follows cor:api:100:01 (member -> that org, non-member -> empty page, no disclosure, no admin bypass). Slug-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only.
orgId ID
limit Int
offset Int
resendSender ResendSender Fetch one sanitized BYO Resend sender config; null for missing or inaccessible.
ref ID!
resendSenders ResendSendersPage! Uniform paginated BYO Resend sender list scoped to the caller's member orgs.
orgId ID
limit Int
offset Int
homeAssistantInstanceOps [HomeAssistantOp!] The ops one registered instance exposes (the closed catalog filtered by the row's allowlist) — what authors browse to pick data.tools entries; what this returns IS what a run can call. Null when the row does not exist or the caller is not a member of its org; a disabled instance errors with HA_INSTANCE_DISABLED.
ref ID!
exchangeMessages [ExchangeMessage!]!
connectionId ID!
top Int
filter String Deprecated: raw provider filters are gone; only 'isRead eq false' still translates. Use unreadOnly.
unreadOnly Boolean
exchangeFolders [ExchangeFolder!]!
connectionId ID!
calendars [CalendarInfo!]! Calendars the connected account can see. Grant scope: calendar.read.
connectionRef ID!
calendarEvents [CalendarEvent!]! Events in a time window (recurring events expand to instances, ordered chronologically). start/end are RFC 3339; calendarId defaults to the account's primary calendar. Grant scope: calendar.read.
connectionRef ID!
calendarId String
start String
end String
query String Free-text search over event fields.
top Int
calendarEvent CalendarEvent! One event by id. Grant scope: calendar.read.
connectionRef ID!
eventId ID!
calendarId String
calendarSchedule [ScheduleFreeBusy!]! Free/busy intervals for one or more schedules (calendar ids or addresses the account can read; defaults to the account's primary calendar). Structurally capped at yes/no busy windows — never event contents. Grant scope: calendar.freebusy.
connectionRef ID!
start String!
end String!
schedules [String!]
driveFiles DriveFilePage! Browse or search the connected drive. With no search criteria, lists the children of folderId (default: the drive root), folders first. Any of query/nameContains/mimeType/modifiedAfter switches to a search, most recently modified first. Grant scope: drive.read.
connectionRef ID!
folderId ID
query String Full-text search over file content.
nameContains String
mimeType String Exact MIME type filter.
modifiedAfter String RFC 3339 lower bound on last modification.
top Int
pageToken String
driveFile DriveFile! File metadata by id. Grant scope: drive.read.
connectionRef ID!
fileId ID!
driveFileExport DriveFileExport! Export a drive file through the connection's provider tool. Grant scope: drive.read is required for an App context's covering connection grant. Without an App context, the caller must own the connection; org administration alone does not grant access. The server delegates format conversion, binary-file refusal and size validation to that tool; it does not independently enforce those provider guarantees here. Returns the tool's content, MIME type and format.
connectionRef ID!
fileId ID!
format DriveExportFormat
apps AppsPage! Uniform paginated app list (#473) — replaces the org-ADMIN apps(orgId!) and the member myApps. Scope: Apps in the caller's member orgs (App doesn't carry a userId, so org membership is the routing); platform ADMIN/OWNER unscoped get every live App. orgId follows cor:api:100:01 (member -> scope, non-member -> empty page, no disclosure, no admin bypass). Name-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only. filter.ownedByMe (#782) narrows to the caller's own user-owned (org-less) Apps for every caller including platform admins.
filter AppFilter
orgId ID
limit Int
offset Int
app App Fetch an App (member of the App's org, or platform ADMIN — the myApps exposure bar; #473 relaxed this from org ADMIN for read parity with the list). 'ref' accepts the entity's ID or URN.
ref ID!
myApp App The App authenticated by the current AppKey (null for JWT users without an App)
agent Agent The uniform single-agent read. Uses the shared Agent read gate, including PUBLIC visibility and owner-aware access to user-owned Agents. An absent or unreadable Agent returns null; malformed or under-qualified refs remain input errors. Nested fields keep their own exposure gates. 'ref' accepts the entity's ID or URN.
ref ID!
agentTaskList [AgentListedTask!]! #1892 (hrn:node:hadronmemory.com:specs:cor:dmo:050:15) - an Agent's tasks, across its base chain: every runnable node in its effective system memory, and every task the tasks index of an Agent in the chain lists, each once. A task an index lists carries that edge's name as its trigger, the nearest index's where two list it. Readable by whoever may read the Agent's system memory; a listed task outside the chain's memories is returned only when its own memory is readable too. Refused as AGENT_NOT_FOUND otherwise. The MCP tool hadron_agent_tasks returns the same list. Accepts the Agent's ID or URN. #2421 experiment: optional symptom ranks only runnable effective-chain tasks with non-empty abstracts; summary vectors and abstract-only lexical matches share hybrid ranking. At most 3 candidates (limit defaults to 3, larger values clamp); empty symptom or non-positive limit is BAD_USER_INPUT. Without symptom the list is unchanged. matchedBy identifies ranking inputs.
ref ID!
symptom String
limit Int
agentProcessList [AgentListedProcess!]! #1892 (hrn:node:hadronmemory.com:specs:cor:dmo:050:16) - an Agent's processes: the ones its own processes index lists (STARTS, with the edge's trigger), then the ones with a stage edge (named 'stage ...') to one of its agentTaskList tasks (INVOLVED, no trigger), each once. Same gate as agentTaskList; the MCP tool hadron_agent_processes returns the same list. Accepts the Agent's ID or URN.
ref ID!
agentServedBootPrompt AgentServedBootPrompt! #3843 (hrn:node:hadronmemory.com:specs:cor:agt:040:05, hrn:node:hadronmemory.com:specs:cor:agt:040:10) - the boot prompt an Agent would be served now, rendered, for a caller that binds no worker (an MCP-only agent; the MCP tool hadron_agent_boot_prompt returns the same text). A pure read: it binds nothing, starts or ends no session and records no ServedPrompt; the answer is the current serve, never what a session was given, so an approval between two calls can change it. Without appRef it reads the Agent's own pointer, visible to a caller who may read the Agent's system memory. With appRef it reads what a chat in that App would be given (the install's pointer, then the Agent's), for a participant of that App (an App key only for its own App) where the Agent is installed and the caller may chat with it. Every caller who fails a gate, a missing or not-installed App and a lapsed App licence get the same AGENT_NOT_FOUND as a nonexistent Agent. Past the gate, a serve refusal is thrown as its typed BOOT_PROMPT_* error (NOT_SET, TARGET_DELETED, NOT_APPROVED, NOT_SIGNED) with surface 'chat'. llmModel is the model the client reports, filled into session.llmModel (empty when omitted); it is rendering text, never an identity or authority claim.
agentRef String!
appRef String
llmModel String
orgBootPromptSigning OrgBootPromptSigning! #2973 PR2 / hrn:node:hadronmemory.com:specs:cor:agt:040:09: the organisation's boot-prompt signing switch and whether it is enforced. Only the organisation's current ADMINs and OWNERs, acting as themselves. A worker session (an admin's included), an App key, an App run, impersonation, a non-member (a platform admin included), a revoked member, a member below ADMIN, and an organisation that does not exist are all refused with the same FORBIDDEN.
org ID!
orgBootPromptSigningPreview BootPromptSigningPreview! #2973 PR2 / hrn:node:hadronmemory.com:specs:cor:agt:040:09: what switching the organisation's boot-prompt signing on would change, paged (first at least 1, default 20, served at 200 when more is asked, hrn:node:hadronmemory.com:specs:cor:api:120:04; after is the previous page's endCursor). The audience and refusals are orgBootPromptSigning's.
org ID!
first Int
after String
agents AgentsPage! Uniform paginated agent list (#473). Scope: Agents owned by the caller's member orgs; platform ADMIN/OWNER unscoped get every live Agent. orgId follows cor:api:100:01 (member -> scope, non-member -> empty page, no disclosure, no admin bypass). filter narrows by type / visibility. filter.ownedByMe (#782) narrows to the caller's own user-owned (org-less) agents for every caller including platform admins. Name-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only.
filter AgentFilter
orgId ID
limit Int
offset Int
publicAgents AgentsPage! #551 — the public-agent marketplace slice: every live PUBLIC agent, readable by ANY caller (no membership required), so an org can discover foreign public agents to subscribe to (008/009 AgentOrgGrant; hadron-portal#486). Kept SEPARATE from agents() on purpose: agents() stays bounded to the caller's own orgs, and the cross-org widening is this explicit, paginated surface rather than a value in a filter. filter.type narrows by AgentType; filter.visibility is IGNORED (the slice is PUBLIC by definition). Field-level exposure: a PUBLIC agent publishes its OWN definition (systemMemoryId / memoryItems / imports) to every caller — that is what a marketplace listing is (#551). The fields that surface OTHER tenants (apps / appAgents / appCount / orgGrants / importedBy) are scoped to the caller's own access and come back empty for an outsider (#552, #757). Name-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only.
filter PublicAgentFilter
limit Int
offset Int
myAgentSubscriptions [AgentSubscription!]! 005-agent-subscription FR-005: AgentSubscriptions held by the authenticated user. Read-only in v1.
myAgentSubscriptionsPage AgentSubscriptionPage! #2213 — `myAgentSubscriptions` as a page: the same rows (no user or an impersonated request gets the empty page where the old field gives []), newest first with agentId ascending on a tie, and the real total (hrn:node:hadronmemory.com:specs:cor:api:120:04). `limit` defaults to 20, 0 returns the count only, a negative limit is 0 and a limit over 200 is served as 200 (never refused). `offset` below 0 is 0. A consumer that decides on this list must follow the pages to the end; `myAgentSubscriptions` stays the complete set.
limit Int
offset Int
agentSubscriptions [AgentSubscription!]! 005-agent-subscription FR-022: list all AgentSubscriptions for an Agent. Authorized for ADMIN/OWNER of the Agent's owning org. Accepts the entity's ID or URN.
agentRef ID!
agentSubscriptionsPage AgentSubscriptionPage! #2213 — `agentSubscriptions` as a page: the same gate and refusals (an Agent the caller cannot read answers as absent; otherwise ADMIN of its owning org), the same rows, newest first with userId ascending on a tie, and the real total (hrn:node:hadronmemory.com:specs:cor:api:120:04). A refused caller gets the old field's error, never a total. `limit` defaults to 20, 0 returns the count only, a negative limit is 0 and a limit over 200 is served as 200 (never refused). `offset` below 0 is 0. A consumer that decides on this list (who is subscribed) must follow the pages to the end; `agentSubscriptions` stays the complete set. Accepts the entity's ID or URN.
agentRef ID!
limit Int
offset Int
appNodes [Node!]! Nodes in the App's current readable installed-Agent memory scope, with eligible inherited system-memory nodes. Participants additionally receive the App's team space; org-authorized readers do not gain that space merely from org membership. Live access, link roles and App scoping constrain the result; this is not every memory linked to any installed Agent. Accepts the App's ID or fully qualified URN. NodeFilter narrows node fields, including objectType, approvalState and minted. Nonempty memoryIds or memoryClasses are rejected with BAD_USER_INPUT: the App scope is authoritative. where and childrenOf are rejected with BAD_USER_INPUT too (#3427, #2832); use findNodes. Unlike findNodes, system-node types are not excluded by default. Deleted content remains subject to recovery authority. NodeFilter.contentScope COMMENTS or ALL can select comments. When contentScope is omitted, nodeType=comment selects COMMENTS; otherwise the default CONTENT excludes comments. Filters on approvalState or minted always exclude comments.
appRef ID!
filter NodeFilter
limit Int
appNodesPage NodePage! #2212 A2 (hrn:node:hadronmemory.com:specs:cor:api:120:04): appNodes as a page. Same admission, filter rules and refusals as appNodes (an unknown or malformed App and a caller who may not read it are refused exactly as there; a soft-deleted organization and an empty scope are the empty page), but total counts every node appNodes would return for the filter and hasMore says whether rows remain past this page. Ordered by loc, then id, so the order is stable across the App's memories. Default page 20, limit: 0 is count-only, a negative limit is 0, a limit over 200 is served as 200, a negative offset is 0. The filter's memoryIds, memoryClasses, where and childrenOf are refused, as on appNodes. Accepts the App's ID or URN.
appRef ID!
filter NodeFilter
limit Int
offset Int
memoryLocSegments LocSegmentsPage! #3456 (hrn:node:hadronmemory.com:specs:cor:api:090:05): one page of the distinct next loc segments under parentLoc ("" for the root), including a branch with no node of its own. Reads over exactly the nodes findNodes would read for the same memoryIds with no query: the same readable set, access intersection, defaults and inheritance. memoryIds is required and non-empty (an empty list is BAD_USER_INPUT); when no entry survives the gate the answer is the empty page, never the caller's default scope. An unreadable, unresolvable or empty memory, and a parent with nothing at or under it, all give the identical empty page. Rows are grouped by memory id; inside a memory, node-backed segments with a position come first by position, then every other segment by name (ruling 0217). Default page 20, cap 200 (larger is served as 200); after is the previous page's endCursor.
memoryIds [ID!]!
parentLoc String!
limit Int
after String
appMemoryScope AppScopedMemoryPage! #2190 (hrn:node:hadronmemory.com:specs:cor:dmo:050:17): the memories appNodes reads for this caller, one row per memory with every reason it is in scope, ordered by memoryUrn and paged (default 20, cap 200; over the cap returns a page of the cap). Same entry and admission as appNodes, so an external App participant appNodes admits is answered here too, and a refused caller gets appNodes' error. Every memory in the caller's scope is listed, including empty ones, so nothing is withheld; total 0 means no memories, and is also the answer for an App in a soft-deleted organization. Rows are leaves. Accepts the App's ID or URN.
appRef ID!
limit Int
offset Int
memoryNodes GraphNodesPage! Slim, paginated node list for rendering a memory's graph view (issue #466). Returns ONLY the fields a node-link graph draws (id, loc, name, nodeType, tags) — no content / abstract / data / tokens / edges — so the payload is a fraction of the full node fragment. The graph view loads this to completion (page by page) and renders nodes, THEN loads memoryEdges to draw the links. memoryRef accepts the memory's ID or URN; a memory the caller can't read returns an empty page (total 0, no existence disclosure). Paged via limit (default 20, hard-capped 2000) + offset; total is the memory's full node count so the client can show "N of M" and know when it has paged them all. limit: 0 returns an empty page with just the total — the cheap "how big is this memory" node count. Deterministic loc-ascending order so offset paging never drops/duplicates. Temporarily OFF by default (#2990, server env GRAPH_VIEW_DISABLED): every memory, readable or not, answers the empty page (nodes [], total 0) without a read.
memoryRef ID!
limit Int
offset Int
memoryEdges GraphEdgesPage! Slim, paginated edge list for a memory's graph view (issue #466) — phase two after memoryNodes. Returns endpoint IDs only (sourceId/targetId); the client already holds the nodes by the time it draws edges, so it maps id -> node itself. Scoped by the edge's denormalized memoryId (edges whose SOURCE is in the memory); a cross-memory edge may reference a target outside this memory, which the client drops as a dangling endpoint. Same access gate, paging, and deterministic loc-ascending order as memoryNodes. Temporarily OFF by default like memoryNodes (#2990): the empty page (edges [], total 0) for every memory.
memoryRef ID!
limit Int
offset Int
appAIConfig AppAIConfig Decrypted AI config for an App (org ADMIN of the App's org). Accepts the entity's ID or URN.
appRef ID!
appKeys [AppKey!]! List keys for an App, only for whoever manages the App (hrn:node:hadronmemory.com:specs:cor:dmo:050:12; hrn:node:hadronmemory.com:specs:cor:acl:010:01), as themselves, or through their held worker on a validated `instruction` (S6, ruling 0098). An admitted instructed call records one team event (ruling 0111): the worker, the holder, the App and the instruction, never a key. Never an App key, a host-launched or uninstructed worker session, a run or an impersonated request. Accepts the entity's ID or URN.
appRef ID!
instruction ActInstructionInput
appKeysPage AppKeyPage! #2213 — `appKeys` as a page: the same manager-only gate and refusals (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), the same live keys, newest first with id descending on a tie, and the real total (hrn:node:hadronmemory.com:specs:cor:api:120:04). An instructed call (`instruction`, as on `appKeys`) records one team event per call, so each page records one. A refused caller gets the old field's error, never a total. `limit` defaults to 20, 0 returns the count only, a negative limit is 0 and a limit over 200 is served as 200 (never refused). `offset` below 0 is 0. A consumer that decides on this list (the admin key inventory) must follow the pages to the end; `appKeys` stays the complete set. Accepts the entity's ID or URN.
appRef ID!
limit Int
offset Int
instruction ActInstructionInput
myUserApiKeys [UserApiKey!]! 025-oauth-for-mcp FR-004: list the calling User's API keys (active + revoked, createdAt DESC). Powers Phase 3's portal revocation UI (SC-006). Rejected with UNAUTHENTICATED for AppKey-resolved callers (no user in context). Impersonation is refused with Forbidden.
includeHidden Boolean #2298: include keys the owner hid with setUserApiKeyHidden. Default false.
myUserApiKeysPage UserApiKeyPage! #2213 — `myUserApiKeys` as a page: the same refusals (UNAUTHENTICATED with no user in context, Forbidden under impersonation), the same rows (active and revoked; hidden keys only with includeHidden), newest first with id descending on a tie, and the real total (hrn:node:hadronmemory.com:specs:cor:api:120:04). `limit` defaults to 20, 0 returns the count only, a negative limit is 0 and a limit over 200 is served as 200 (never refused). `offset` below 0 is 0. A consumer that decides on this list must follow the pages to the end; `myUserApiKeys` stays the complete set.
includeHidden Boolean #2298: include keys the owner hid with setUserApiKeyHidden. Default false.
limit Int
offset Int
myPasskeys [PasskeyCredential!]! #1631 PR3: the caller's own passkey records, revoked ones included, newest first. Only the owner sees them: an App key or an impersonation session is refused. Registering and revoking are interactive ceremonies on the server-hosted pages, never GraphQL. Present only while passkey registration is enabled.
agentAIConfig AgentAIConfig Agent AI config (org ADMIN) — returns the decrypted API key so the portal backend can make LLM calls on behalf of the user. 036-ai-service-config: registry-backed (the Agent's config named 'default'). Prefer resolveAIConfig for new callers. Accepts the entity's ID or URN.
agentRef ID!
aiServiceConfig AiServiceConfig The uniform single-config read. 'ref' is the config's ID or its hrn:aiconf: URN (#3857, hrn:node:hadronmemory.com:specs:cor:urn:010:01; see AiServiceConfig.urn). On the URN path a config the caller may not read answers null, exactly as a missing one does, because names such as 'default' are guessable (hrn:node:hadronmemory.com:specs:cor:api:120:01); the ID path keeps the posture below. Masked: never returns key material, only hasApiKey + apiKeyPreview (resolveAIConfig is the privileged decrypted read). Auth mirrors the list: platform ADMIN/OWNER for HADRON_SERVER; org ADMIN for ORGANIZATION; the App/Agent's owner or owning-org ADMIN for APP/AGENT. User-owned Apps and Agents use their strict owner-only credential gate, even for platform admins. Denied throws Forbidden, except an unreadable owning Agent answers AGENT_NOT_FOUND. A missing config returns null.
ref ID!
aiServiceConfigs AiServiceConfigsPage! 036-ai-service-config: masked, paginated list of AI configs (#473). Never returns key material — only hasApiKey + apiKeyPreview. filter names the owning entity. Auth: platform ADMIN/OWNER for HADRON_SERVER owners; org ADMIN of the owning org for ORGANIZATION / APP / AGENT owners. filter omitted entirely = the platform ADMIN/OWNER cross-owner view of every config (non-admin callers must filter). Name-ascending order (id tiebreak); limit default 20 / cap 200; limit: 0 -> count only.
filter AiServiceConfigFilter
limit Int
offset Int
scope Scope Spec 049 Phase 2 — the uniform single-scope read (cor:api:120). 'ref' is the scope's ID (a Scope has no URN yet). Null when missing OR when you may not read it — no existence disclosure. Read gate: an org scope to that org's members, an App scope to the App's participants, an Agent scope to whoever may read the Agent.
ref ID!
memoryConfig MemoryConfig! #1325 — a memory's config, for the memory's managers only. For anyone else, and for a missing memory, the same MEMORY_NOT_FOUND.
memoryRef ID!
memoryConfigTemplate MemoryConfigTemplate #1325 part (c) — one template you manage, by id; null for anything else, including a missing or deleted one.
ref ID!
memoryConfigTemplates MemoryConfigTemplatesPage! #1325 part (c) — the templates you manage, name-ascending. Default page 20, at most 200; limit 0 returns the count only.
filter MemoryConfigTemplateFilter
limit Int
offset Int
scopes ScopesPage! Spec 049 Phase 2 — paginated list of the scopes you may read, optionally narrowed by owner, by an App's resolution context, by name, and by the cor:api:100:01 orgId (member-gated, no admin bypass; non-member ⇒ empty page). Name-ascending (id tiebreak); limit default 20 / cap 200; limit: 0 ⇒ count only.
filter ScopeFilter
orgId ID
limit Int
offset Int
scopeExplain ScopeExplanation Spec 049 Phase 2 — explain a scope for YOU. Pass scopeRef, or a bare name plus appRef (a name is unique only per owner, so it resolves in an App's context: App › Agent › organization, never unioned — two installed Agents each owning the name is SCOPE_NAME_AMBIGUOUS and you choose by scopeRef). Returns the readable memories in order, the dropped COUNT, the shadowed scopes, and with `loc` which memory would win for that address.
scopeRef ID
name String
appRef ID
loc String
channel Channel Spec 049 Phase 4 — the uniform single-Channel read. 'ref' is the Channel's id or its ADDRESS — the chat root's node URN, which is `Channel.chatRootUrn` and what `createChannel(memoryRef, loc)` composes to (#1171). Null when missing, when the ref names nothing, OR when you may not read its host memory — identically, so this is never an existence oracle.
ref ID!
channels ChannelsPage! Spec 049 Phase 4 — Channels whose host memory you may read, narrowed by an App (its host memories' Channels) or by one memory, and by the cor:api:100:01 orgId. Loc-ascending (id tiebreak); limit default 20 / cap 200.
filter ChannelFilter
orgId ID
limit Int
offset Int
registerEntry RegisterEntry Spec 049 Phase 5 — one register entry. Null when missing OR when you may neither read its Channel's host memory nor stand on the row's owner side.
ref ID!
registerEntries RegisterEntriesPage! Spec 049 Phase 5 — register entries you may read (§8.6), narrowed by owner (an App or an organization), Channel, or attendee (a Worker or an Agent), and by the cor:api:100:01 orgId. A filter naming something foreign returns the same empty page as one naming nothing. Oldest first; limit default 20 / cap 200.
filter RegisterEntryFilter
orgId ID
limit Int
offset Int
attendeeRegister [RegisterViewRow!]! Spec 049 Phase 6 — an attendee's RESOLVED register: the rows that apply to a Worker (workerRef) or to an Agent in an App (agentRef + appRef), one per Channel, with YOUR standing on each host memory. The relay reads this instead of a configured appRef. Gated on App participation (the same gate as the Worker's briefing); a foreign or nonexistent attendee is an empty list.
workerRef ID
agentRef ID
appRef ID
channelReadState ChannelReadState Spec 049 Phase 7 — an attendee's cursor on a Channel (attendeeRef: a Worker, or an Agent with appRef). Same gate as attendeeRegister; lastSeenSeq 0 when the attendee has never checkpointed there; null when unreadable or unknown. channelRef: the Channel's id or its address (`Channel.chatRootUrn`, #1171).
attendeeRef ID!
appRef ID
channelRef ID!
teamAttention TeamAttentionResult! #1353 v1 attention query, retired by #1384. This field always returns UPGRADE_REQUIRED; use teamAttentionPage for bounded polling. Pass an existing v1 since token to teamAttentionPage to carry its watermark forward. Neither operation changes read state.
appRef ID!
since String
teamAttentionPage TeamAttentionPage! #1384 paged (v2) attention poll — the bounded successor to teamAttention (v1 answers UPGRADE_REQUIRED). Each call decrypts at most scanLimit rows (encrypted Channels), counts plaintext Channels with bounded SQL aggregates (#1779: a window of 200 seqs per scanLimit unit per Channel visit, 400 per call), and emits at most limit Worker/Channel pairs; continue with page while nextPage is present. The final page alone carries adoptableSince — adopt it only after EVERY listed nudge was accepted; on any partial failure retain the prior watermark and restart the scan (duplicates, never loss). An existing v1 since token starts a scan, carrying the watermark forward. Never changes read state.
appRef ID!
since String
page String
limit Int
scanLimit Int
teamAttentionPreviewPage TeamAttentionPreviewPage! #1384 paged switchover preview — same bounded scan as teamAttentionPage, full-backlog accounting. The apply proof exists ONLY on the final page of a completed preview; confirmTeamAttentionSwitchover (apply) is unchanged.
appRef ID!
page String
limit Int
scanLimit Int
teamAttentionSwitchoverPreview TeamAttentionSwitchoverPreview! Preview the explicit baseline switchover for the operator's current live Workers. Read-only: inspect the exact cursors, heads and unread counts, then pass proof to confirmTeamAttentionSwitchover within ten minutes.
appRef ID!
resolveAIConfig ResolvedAiConfig! 036-ai-service-config: resolve a config name for an execution context and return its identity, with decrypted credentials only for a caller authorized to manage the selected source (successor to agentAIConfig/appAIConfig). Walk: App -> Agent -> Org (of the App, else of the Agent) -> HadronServer; disabled configs are skipped. When name is omitted, 'default' is resolved. When an explicit name misses, resolution falls back to 'default'; if that also misses, errors with NoAiConfigAvailableError. Consumers (webhooks, scheduled tasks, the portal chatbot) reference configs by name only — pass the name plus the execution context, never credentials. Auth: a named App uses its own owner/org ADMIN gate, including strict owner-only access for a user-owned App. A named Agent must be installed and live-licensed in that App. Without an App, an org Agent requires org ADMIN; a host-only context requires platform ADMIN/OWNER. A user-owned Agent is strictly owner-only, including when an App is also named. With no effective org, its owner can decrypt that Agent's own config or a user-owned App's config; a host fallback is unavailable through this query. A user-owned App's owner needs the outer source's own authority to decrypt an installed Agent or org config; its App ownership alone grants only its App config. A HADRON_SERVER fallback can back a server-side call, but only a platform ADMIN/OWNER may receive its plaintext key. An otherwise authorized context without the selected source's credential authority receives the config identity with apiKey and params null, without decrypting a key. appRef/agentRef accept the entity's ID or URN.
name String
appRef ID
agentRef ID
chatId ID #3957 (hrn:node:hadronmemory.com:specs:cor:dmo:050:10): a chat of appRef. With it, the chat's stored aiConfigChoice wins, else the App's chatbot config, else the `default` walk above; a choice counts only while its config exists, belongs to appRef and is enabled. A chat that is not one of appRef's chats answers as a missing chat.
aiProviderEndpoints [AiProviderEndpoint!]! #1373: the known endpoints for a provider — the server's single suggestion list, so the portal and the CLI render the same choices and neither hardcodes a URL. Empty for an unknown provider and for bedrock (its endpoint comes from the region). Public reference data (vendor URLs), so it needs no auth.
provider String!
resolveAiServiceConfigs [AiServiceConfig!]! 036-ai-service-config: the MASKED set of configs RESOLVABLE in an execution context — every distinct config name a chat in this context could select. Populates a config picker in the chatbot UI. Same walk as resolveAIConfig (App -> Agent -> Org (of the App, else of the Agent) -> HadronServer), but returns ALL names instead of resolving one: configs are deduped by name with the innermost owner winning, so each entry is the row the resolution walk selects for that name; this masked listing does not grant permission to decrypt it. Only the Agent named here contributes — sibling Agents installed in the same App are not consulted. Disabled configs are skipped. Never returns key material. hasApiKey remains visible; params and apiKeyPreview are null unless the caller manages the selected source. Auth: scoped to one App's chat context. A non-admin caller MUST pass an appRef, be a member of that App, and (when an agentRef is given) the Agent must be installed and live-licensed in that App. Because the result is masked (no key material), App membership — not org admin — is the bar, unlike resolveAIConfig and the aiServiceConfigs management list. Platform ADMIN/OWNER are always allowed and may omit appRef. appRef/agentRef accept the entity's ID or URN.
appRef ID
agentRef ID
chatAiConfigChoices [ChatAiConfigChoice!]! #3957 (hrn:node:hadronmemory.com:specs:cor:dmo:050:10): what a chat of this App may choose from — the App's OWN enabled AI configs plus one `default` entry, which resolves through the App -> Agent -> Org -> Host walk at turn time. Send an entry's `value` back as the chat's aiConfigChoice. Never a key, key preview, params or endpoint. Any App member may call it (a platform admin too); anyone else, a missing App and a request that is not a signed-in person get the same APP_NOT_FOUND answer.
appRef ID!
chatEffectiveToolChoice ChatToolChoice #4042 (hrn:node:hadronmemory.com:specs:cor:dmo:050:10, hrn:node:hadronmemory.com:specs:cor:acl:030:01): the tool-choice decision the chat turn will use for this chat's effective config: same predicate, same resolve order as the turn (the chat's stored choice, else the App's chatbot config, else the `default` walk). Null when no level matches, and for a user-owned App whose walk lands on the platform's config (which that App may not use); otherwise non-null. Authorized through the single-chat read gate chatHistory uses: a chat has no access layer of its own, so read is decided by the host memory. A chat the caller may not read answers exactly as a chat that does not exist. The decision only: no key, id, name, provider or model.
chatId String!
chatToolChoiceFor ChatToolChoice! #4042 (hrn:node:hadronmemory.com:specs:cor:dmo:050:10): the chat turn's tool-choice decision for an UNSAVED (provider, model) pair, by the same one predicate, judged verbatim. Pure: reads no config rows, decrypts nothing, calls no provider and meters no usage. Any signed-in caller; no owner context is consulted. An unknown or unlisted provider or model answers FORCED, never a refusal.
provider String!
model String!
chatServedPrompts ServedPromptsPage! #2862 / hrn:node:hadronmemory.com:specs:cor:agt:040:03: a chatbot chat's served-prompt records, by chat id, and nothing else about the chat. The same read as Chat.servedPrompts (newest first, default 50, cap 200): readable only by whoever manages the App named by the chat's first record, and only that App's records. Everyone else, an unknown chat id and serving switched off all get an empty page, never an error. Never returns a Chat.
chatId ID!
limit Int
offset Int
myChats [Chat!]! Saved chats for the current user in their personal memory for an agent. Newest first. Accepts the entity's ID or URN.
agentRef ID!
limit Int
offset Int
myChatsPage ChatPage! #2212 A3 (hrn:node:hadronmemory.com:specs:cor:api:120:04): myChats as a page. Same gate and refusals as myChats (unauthenticated and impersonated callers are refused; an unknown Agent and a caller with no readable memory get the empty page), and the same chats: the caller's own for the Agent plus the shared chats of Apps the caller is a member of. total counts exactly those chats and hasMore says whether rows remain past this page. Newest first by last update, then by id, so the order is stable across pages while the chats do not change; a chat updated between requests can move pages. Default page 20, limit: 0 is count-only, a negative limit is 0, a limit over 200 is served as 200, a negative offset is 0. Accepts the Agent's ID or URN.
agentRef ID!
limit Int
offset Int
chatHistory [ChatMessage!]! Message history for a saved chat. Returns plain role/content pairs suitable for feeding back into an LLM. limit bounds the transcript to its MOST RECENT messages (default 20), and they are returned oldest-first. Stated because it was not: the window used to be taken from the other end, so a chat longer than the limit returned its opening forever (#1111), and a client author had no written contract to check that against. Contract: cor:cht:050:01. beforeSeq (#1116) pages BACKWARD: only messages with seq strictly LESS than it are considered, and the window then returns the newest "limit" of those -- the page immediately preceding the cursor, still oldest-first. It is the mirror of teamChatMessages' sinceSeq: pass the OLDEST seq you hold, as you would pass the newest to page forward. Omit it for the tail. There is no total -- the field returns the page and nothing else. A page SHORTER than the limit is a truthful end-of-data under that cursor, and only here: this resolver applies every filter inside the query and never drops a row after the database take, so the take IS the page. Do not carry the same-looking inference to reads that overfetch and post-filter; there a short page can still mean rows were removed. Two boundaries worth knowing before you build on it: - A message with NO seq is older than every numbered one (cor:cht:050:02), so every cursor includes such messages. They are reachable, but they cannot themselves BE a cursor -- a legacy chat holding more counterless messages than one page cannot be paged through them. Only pre-#919 transcripts are affected. - seq is unique going forward but NOT on pre-#919 rows. Where two legacy messages share a seq, a cursor at that value excludes both, so paging can skip the sibling. See #992 for the underlying gap.
chatId String!
limit Int
beforeSeq Int
teamChatMessages TeamChatMessagesPage! Read a team App's chat (#939), seq-ordered ascending, as a uniform { items, total } page. sinceSeq is a watermark cursor: only messages with seq STRICTLY GREATER than it are returned (pass the last seq you have seen). With neither cursor nor offset, the NEWEST page is returned, still ascending. Pass sinceSeq: 0 to start a forward walk at the oldest message. beforeSeq (#1116) is its BACKWARD mirror for scroll-up paging: only messages with seq STRICTLY LESS than it are considered, and the NEWEST limit of those come back -- the page immediately before the cursor, still ascending. The two compose, so passing both reads a bounded slice. TeamChatMessagesPage.total counts that cursor range and the mentionsRef filter before paging, not the whole team-chat history. An explicit offset retains oldest-first positional paging for existing clients; prefer cursors for new reads. offset is IGNORED when beforeSeq is given: a cursor exists precisely because a position is unstable while workers keep posting, and honouring both would put that race back. mentionsRef filters to messages whose stored envelope mentions the referenced worker (a Worker id or name of THIS App, retired included) or user (handle/id) — matching runs against the mention tokens extracted at write time, never by re-parsing bodies. For a worker it returns what reaches that worker (#2020): its name, replies to it, and an @all/@team broadcast the server stamped at post time because its author could wake everyone (hrn:node:hadronmemory.com:specs:cor:agt:080:14); never the worker's own posts. A user ref matches the handle alone. The ref must name this App's own staff or members (a Worker of the App, an AppMember, or the caller); an unresolvable or foreign mentionsRef yields the empty page identically (no existence oracle). limit defaults to 20 (cap 200); limit: 0 returns only total. Authorization: an AppMember of the App (any role), an org member with CONTRIBUTOR+ on the App's org, the owner of a user-owned App, or the App's own key (a pure App-key principal may READ its team chat). Error codes (extensions.code): FORBIDDEN (an authenticated caller who is not a participant), UNAUTHENTICATED (no principal at all; checked before the App is resolved, so it answers identically whether or not the App exists). appRef and mentionsRef accept the entity's ID or URN.
appRef ID!
replyToSeq Int Direct replies only; target excluded. Unknown/deleted target: TEAM_CHAT_REPLY_NOT_FOUND. AND-composes with all filters; a partial window never advances the read mark.
advanceReadState Boolean Only false suppresses automatic read-cursor advancement. Session attribution, read usage and the eligible owned-session heartbeat remain. Omitted, null and true preserve normal contiguous-page acknowledgement; callers opting out acknowledge explicitly after successful delivery.
sinceSeq Int
beforeSeq Int
mentionsRef ID
teamHeadRef ID Stable authorized head ID; mutually exclusive with untagged.
teamHeadRefs [ID!] #3759 — several head IDs at once: messages tagged with ANY of them. Each entry is checked as teamHeadRef is, and one bad entry refuses the whole call with the same TEAM_CHAT_TEAM_HEAD_INVALID text. Mutually exclusive with teamHeadRef and with untagged (true or false). At most 20 entries (raw length, duplicates count; [A, A] reads as [A]); more is BAD_USER_INPUT before any entry is looked up. An empty list is no team filter. A non-empty list needs team metadata access, checked before any entry.
untagged Boolean Select no stored head identity (legacy absent or explicit empty). Requires metadata access.
limit Int
offset Int
teamChatSearch TeamChatSearchPage! Search a team App's chat history (#2299, hrn:node:hadronmemory.com:specs:cor:agt:020:04): a literal, case-insensitive substring of the message text (% _ and the backslash are ordinary characters), newest first, one channel at a time, through the same read gate as teamChatMessages. The search matches what a read shows (the canonical read projection), returns references only, and never moves a read position, delivered mark or attention. query is 2 to 200 characters (code points, untrimmed); outside that is TEAM_CHAT_SEARCH_QUERY_LENGTH, answered the same for every caller before any message is read. limit defaults to 20 and is clamped to 50 (below 1 is BAD_USER_INPUT). Each call scans at most 1,000 messages; see TeamChatSearchPage for complete and cursor. A chat hosted in an encrypted memory is TEAM_CHAT_SEARCH_ENCRYPTED, never an empty page. An App with no team chat yet answers the complete empty page. appRef accepts the entity's ID or URN.
appRef ID!
query String!
limit Int
cursor String
channelMessageSearch TeamChatSearchPage! Search ANY Channel's history by ref (its id, or its address), the Channel-addressed twin of teamChatSearch with the same contract (#2299). A Channel you may not read, or one that does not exist, is CHANNEL_NOT_FOUND, identically.
channelRef ID!
query String!
limit Int
cursor String
channelMessages TeamChatMessagesPage! Spec 049 Phase 8 — read ANY Channel by ref (its id, or its address — `Channel.chatRootUrn`, #1171), with teamChatMessages' cursors, mentions filter and paging; teamChatMessages is the appRef → App.defaultChannel convenience over this. Authorization is the host App's team-chat read gate; a Channel you may not read — or one that does not exist — is CHANNEL_NOT_FOUND, identically. TeamChatMessagesPage.total has the same cursor- and mention-filtered meaning as for teamChatMessages, before paging.
channelRef ID!
replyToSeq Int Direct replies only; target excluded. Unknown/deleted target: TEAM_CHAT_REPLY_NOT_FOUND. AND-composes with all filters; a partial window never advances the read mark.
sinceSeq Int
beforeSeq Int
mentionsRef ID
teamHeadRef ID Stable authorized head ID; mutually exclusive with untagged.
teamHeadRefs [ID!] #3759 — several head IDs at once: messages tagged with ANY of them. Each entry is checked as teamHeadRef is, and one bad entry refuses the whole call with the same TEAM_CHAT_TEAM_HEAD_INVALID text. Mutually exclusive with teamHeadRef and with untagged (true or false). At most 20 entries (raw length, duplicates count; [A, A] reads as [A]); more is BAD_USER_INPUT before any entry is looked up. An empty list is no team filter. A non-empty list needs team metadata access, checked before any entry.
untagged Boolean Select no stored head identity (legacy absent or explicit empty). Requires metadata access.
limit Int
offset Int
expectedIncarnation Int #2181 — pin the read to the Channel incarnation you read. A different incarnation, before or after the page is read, is CHANNEL_INCARNATION_CHANGED with nothing returned and no cursor, check stamp or session resume applied; the server never retargets. Omitted: the read is UNFENCED, as before.
advanceReadState Boolean #2181 — as on teamChatMessages: only false suppresses automatic read-cursor advancement (session attribution, the check stamp and the heartbeat remain), so a pinned page can be acknowledged explicitly after it is delivered.
teamWorkItems TeamWorkItemsPage! Read a team App's worklog (#947) — the provenance query: which sessions (and transcripts) produced this PR? Newest first, as a uniform { items, total } page. ref accepts ANY accepted spelling (URL, short form, canonical) and is matched tool-awarely: with tool 'github' (or none) it is normalized, so 'https://github.com/o/r/pull/371' and 'o/r#371' return the same records. An ownerless github ref such as cli#793 matches every readable canonical ref whose repository ends in cli and number is 793; it never selects one owner. With another tool ref matches the stored verbatim spelling; with no tool it matches either. sessionRef / tool / kind are equality filters; kind must be one of pr, issue, commit, branch, repo when given. limit defaults to 20 (cap 200); limit: 0 returns only total. Authorization: an AppMember of the App (any role), an org member with CONTRIBUTOR+ on the App's org, the owner of a user-owned App, or the App's own key (a pure App-key principal may READ its own App's worklog). appRef accepts the entity's ID or URN; sessionRef is the session id.
appRef ID!
ref String
sessionRef ID
workerRef ID #1035 — everything ONE worker has done, filtered server-side so the page envelope stays correct. Without it a client must fan out over sessions(workerRef:) and merge, which cannot reproduce `total` or a stable offset on the one surface whose whole point is completeness. Accepts a worker id, its URN, or its NAME within this App. A RETIRED worker still resolves — retirement ends the casting, not the history. Records from a session that was never worker-bound carry no worker and do not match. A ref that names nothing readable in this App yields an EMPTY page rather than an error, so this is never an existence oracle for another App's roster.
tool String
kind String
limit Int
offset Int
worker Worker One Worker by ref (#974) — its id, its URN (#991), or (with appRef) its NAME (#1015), the ergonomic handle a human already knows. The name form is ADDITIVE: it is activated by appRef, since a name is unique only within an App. Without appRef the ref must be an id or URN, and anything else refuses WORKER_NOT_FOUND as before. An id or URN wins over appRef rather than being checked against it, so a typo'd URN never degrades into a roster search. Selecting `prompt` re-renders the worker's boot briefing live from the role agent's template — the read that lets an agent recover a briefing it lost to a context compaction, instead of opening a second session or forcing a takeover of itself. Authorization (#1149, hrn:node:hadronmemory.com:specs:cor:dmo:050:11): by id or URN, any signed-in user reads the worker's PROFILE (identity scalars, appName, ownerName, appUrn), and `agent` when the Agent's own visibility admits them; the working-state fields stay masked unless the caller participates in the App (an AppMember at any role, org CONTRIBUTOR+, the owner of a user-owned App, or the App's own key). An anonymous caller, another App's key or run, a support session outside the App's org and a deleted App are refused WORKER_NOT_FOUND exactly as an absent worker. The NAME form stays participant-only: its gate runs BEFORE the lookup and a denial is reported as WORKER_NOT_FOUND, so the roster is not an existence oracle.
ref ID!
appRef ID
workers WorkersPage! A team App's STAFF (#974, cor:agt:020:01 — Workers are the staff; the AppAgent join is the install roster): the App's castings, oldest first, as a uniform { items, total } page. Retired castings are hidden unless includeRetired. Same authorization as worker. appRef accepts the App's ID or URN.
appRef ID!
includeRetired Boolean
limit Int
offset Int
heldWorkers WorkersPage! Workers CURRENTLY held by userRef across Apps the caller may inspect (#1344), oldest casting first. userRef accepts a user id, handle, URN, or email. Missing users, no holds, and holds confined to unreadable Apps all return the same empty page; total and pagination are computed only after the App authorization filter. Retired castings are hidden unless includeRetired. hasLiveSession on each item uses the existing derived idle-window predicate — it means the worker is being driven now, not merely that an unended Session row exists.
userRef String!
includeRetired Boolean
limit Int
offset Int
teamRoles TeamRolesPage! An App's role definitions (#960): every roles:<role> node in the Team Agent's system memory. Ordered by role slug. Same read authorization as workers. #1050: no register projection. This once existed chiefly to answer "which names are still free", which needed the App's FULL roster and so could not be computed client-side — with names no longer allocated from a pool there is no such question, and the read is a plain list of definitions. teamAgentRef disambiguates when more than one installed agent carries a roles: branch (TEAM_AGENT_AMBIGUOUS otherwise); an encrypted system memory without an active session key refuses SESSION_EXPIRED.
appRef ID!
teamAgentRef ID
limit Int
offset Int
agentTickerTemplates [AgentTickerTemplate!]! #2024 — the live ticker templates of an Agent, by name. Anyone who can read the Agent. An Agent the caller cannot read answers as absent (AGENT_NOT_FOUND).
agentRef String!
agentModelGroups [ModelGroup!]! #2831 S1 (hrn:node:hadronmemory.com:specs:cor:agt:060:12) - the model groups an Agent declares, by name. Whoever manages the Agent only (an org OWNER or ADMIN, the owner of a user-owned Agent, a platform admin as for the Agent's other management reads). An Agent the caller cannot read answers as absent (AGENT_NOT_FOUND); a reader who does not manage it gets FORBIDDEN.
agentRef ID!
effectiveModelGroups [EffectiveModelGroup!]! #2831 S1 (hrn:node:hadronmemory.com:specs:cor:agt:060:12) - the model groups in force in an App, resolved live: the Team Agent's groups with the App's overrides applied by name, plus the App's own groups, by name, each with its origin. A participant of the App reads them. An App with no Team Agent has only its own. Refusals: APP_NOT_FOUND, TEAM_AGENT_AMBIGUOUS, SESSION_NOT_BOUND.
appRef ID!
deleteWorkerPreview DeleteWorkerPreview! #3599: preview deleteWorker without deleting anything: the same act gate and typed refusals (WORKER_NOT_FOUND, FORBIDDEN, WORKER_IN_USE), nothing reserved. The real delete still requires confirmNoExternalAttribution and may refuse if anything changed (hrn:node:hadronmemory.com:specs:cor:agt:020:03). A validated instruction claim is recorded (hrn:node:hadronmemory.com:specs:cor:dmo:050:12); the target is its subject. If the delete wins the race, the answer is WORKER_NOT_FOUND. WORKER_REFERENCE_NOT_FOUND refuses a claim only when the acting worker or session no longer exists. No census detail, removal plan, attestation bypass or durable lock/lease is returned.
workerRef ID!
instruction ActInstructionInput
castWorkerPreview CastWorkerPreview! Dry-run castWorker (#964): run the cast's exact resolution — same arguments, same typed refusals (WORKER_AGENT_NOT_FOUND / _AMBIGUOUS / _NOT_INSTALLED, WORKER_NAME_REQUIRED, WORKER_NAME_TAKEN, WORKER_NAME_CONFUSABLE, WORKER_NAME_RESERVED, WORKER_NAME_RESERVED_TEAM_PREFIX (only while TEAM_TAGS_ENABLED), APP_UNINSTALLED), same MINT gate — up to but not including the writes, and return what would be created. A Query, not a dryRun flag: casting a name is the one irreversible act in the team feature (cor:agt:020:02 — permanence), and previewing it must not need a mutation permission model or a fake Worker row. THE PREVIEW RESERVES NOTHING: no lease exists by law (cor:agt:020:03), so a previewed name may be gone at cast time — by design; the cast's uniqueness constraint remains the only allocation primitive.
appRef ID!
agentRef ID
role String
name String
reportsTo ID Worker reference to report to. Requires worker-staffing access and App management. Supply either reportsTo or noTeam: true, never both. Null or a blank reference is invalid.
noTeam Boolean Set to true to record that the worker has no reporting head; do not supply reportsTo as well. Null or false is invalid. Omitting both arguments records no choice (UNSET) when omission is allowed; otherwise the request is refused with WORKER_TEAM_CHOICE_REQUIRED.
instruction ActInstructionInput #3308: a held worker needs this validated instruction or its own live workers.staff grant; host-launched sessions are always headless. The holder still needs staffing rights. Instruction claims are recorded, including previews/no-ops (hrn:node:hadronmemory.com:specs:cor:dmo:050:12, hrn:node:hadronmemory.com:specs:cor:agt:080:24).
agentAssets AssetListResult! v1 — agent-addressed listing. Deprecated; use memoryAssets.
agentUrn String!
mimeType String
skip Int
count Int
includeDeleted Boolean
memoryAssets AssetListResult! v2 (spec 006) — memory-addressed listing. Returns every asset attached to the memory; the gate is the memory's read access. The replacement for agentAssets in the v2 surface. Set mine: true to narrow to the caller's own uploads — a filter on top of the read gate, not a substitute for it. Accepts the entity's ID or URN.
memoryId ID!
mimeType String
skip Int
count Int
includeDeleted Boolean
mine Boolean
assets AssetsPage! Cross-memory asset list (#891) — every file the caller can reach, which is every asset held by a memory they can read. The uniform find-many surface for assets (spec cor:api:120); memoryAssets stays as the per-memory one. The three tabs of a top-level Assets section are filters over this, not separate queries: mine: true, no filter, and orgId respectively.
filter AssetFilter
orgId ID
limit Int
offset Int
assetDownloadUrl AssetDownloadUrl! Mint a short-TTL presigned GET URL for an asset. Default TTL 5 minutes; ceiling 1 hour. Gated on the holding memory's read access and on scan_status = CLEAN.
assetId ID!
ttlSeconds Int
serverInfo ServerInfo! Identity of the hadron-server this GraphQL endpoint is bound to: the server-identity version and the deployment's canonical base URL. The GraphQL counterpart to the hadron_server_info MCP tool — both read the same getDeploymentInfo() helper, so MCP and GraphQL callers get one consistent answer to "which server/API am I talking to?". 'version' is HADRON_SERVER_VERSION — the MCP/API-surface contract version, bumped when the tool/query surface changes in a caller-visible way. It is intentionally NOT the repo's package.json release version. Public — no authentication required. Does NOT expose the DATABASE_URL (it may carry credentials).
nextNode Node The next sibling node under a parent, ordered by seq (#817) — the GraphQL twin of hadron_get_next_node, so guided reading order is no longer MCP-only. parentRef / currentRef take a node PK or a fully-qualified URN (cor:api:140). Omit currentRef to get the FIRST child. Order: seq ascending; a NULL seq sorts LAST, after every explicitly ordered sibling; ties break on loc ascending. Identical to the MCP tool, so the two surfaces cannot present different reading orders. Returns null at the end of the sibling chain, and for a parent that does not exist or the caller cannot read — denied and missing are indistinguishable. A currentRef that is not among the parent's direct children is likewise null rather than an error, so it cannot probe a node's parentage. A MALFORMED ref still throws: a shape error discloses nothing about what exists. Stateless — this is a next-sibling read, not a session-backed cursor.
parentRef ID!
currentRef ID
raw Boolean
renderRunNode String! Render a run/action node WITHOUT executing it (#818) — the GraphQL twin of hadron_run_action, which despite its name executes nothing: it loads the node, resolves its dependency edges, and renders with args. runTask covers the EXECUTE half. This is the render half, for previewing a task before running it (a task run --dry-run), for reading an action's assembled instructions when the CALLER is the executor, and for debugging template/dependency resolution without side effects. A Query because it is side-effect-free, and unlike the MCP tool it records NO action-run UsageEvent — metering a preview would inflate the ledger with actions nobody took. Uses the SAME assembler runTask executes (Mustache compilation via compileTemplate; flow-ROUTING edges skipped, since they are the walker's rails rather than references), so a dry run predicts the real prompt. Two deliberate narrowings relative to execution, both fail-safe: a referenced node the caller cannot READ is omitted rather than inlined (an edge may cross memories), and an edge whose target was soft-deleted is skipped so a preview cannot resurrect removed instructions. NOTE this is NOT the legacy MCP hadron_run_action bundle, which does a literal placeholder replace and inlines every outgoing edge. Where the two differ, this one matches execution. nodeRef is a node PK or a fully-qualified URN (cor:api:140). Denied and missing both raise NODE_NOT_FOUND - no existence oracle.
nodeRef String!
args JSON
validateMemory MemoryValidationResult! Memory health audit (#819) — the GraphQL twin of hadron_validate, which was MCP-only, so the CLI, the portal and CI had no way to answer "is this memory healthy?". Every check is over server-owned state a client cannot compute: abstractOriginHash vs current content, embedding_failed_at (not projected on Node at all), and property-schema conformance. So unlike other gaps there is no slow client-side fallback. Returns TYPED findings so a caller can branch. Gate health and CI on ok, which accounts for both problems and skipped checks. findings is capped by limit (default 200, max 1000); totalFindings reports the full problem count before truncation, excluding informational declarations. Read gate as the rest of the memory reads.
memoryRef ID!
limit Int
specBacklinks [SpecReference!]! #1449 — what refers to the spec at loc in a spec corpus (any memory since #1591): node URNs in the corpus text (inside URLs too) plus real edges from corpus nodes. Exact citation, not descendants. memoryRef accepts the memory's ID or URN.
memoryRef ID!
loc String!
specBacklinksPage SpecReferencePage! #3222 (#2213 S3, hrn:node:hadronmemory.com:specs:cor:api:120:04): specBacklinks as a page. Same read gate and refusals as specBacklinks, and the same list in the same order, so the pages concatenate to exactly what specBacklinks returns. total counts that whole list and hasMore says whether rows remain past this page. Default page 20, limit: 0 is count-only, a negative limit is 0, a limit over 200 is served as 200, a negative offset is 0. Paging bounds the response, not the work: each page still scans the whole corpus. memoryRef accepts the memory's ID or URN.
memoryRef ID!
loc String!
limit Int
offset Int
specDocument SpecDocument! #1302 (R218, hrn:node:hadronmemory.com:specs:cor:spc:030:01) — a Feature's specs as ONE ordered document, built on the server for the CLI and the portal. loc names the Feature (any live spec is accepted, and the document starts with it); the document covers it and its live descendants on colon boundaries. markdown is the whole document in the form of hrn:node:hadronmemory.com:specs:cor:spc:030:02; entries are the same specs with their records, in document order. Same read gate and refusals as specBacklinks: an unreadable and a missing memory answer alike, and an encrypted readable one refuses with SPEC_CORPUS_ENCRYPTED_UNSUPPORTED. A readable memory with no live spec at loc answers NODE_NOT_FOUND (a deleted spec and a never-written loc alike). Over 300 specs it refuses with SPEC_DOCUMENT_TOO_LARGE and extensions.cap, and never returns part of the document. Reads only: nothing is stored, approved or minted. The render time is the only part of the text that differs between two calls over the same specs, approval and mint state, includes, caller access and portal origin. No MCP tool offers this.
memoryRef ID!
loc String!
specUnresolvedReferences [SpecReference!]! #1449 — references in a spec corpus (any memory since #1591) that do not reach a written spec: URNs citing a missing loc or a placeholder, edges to a placeholder or to a deleted spec of the corpus, and pending edges (field pendingEdge) whose target is not a written node yet. Minting refuses while any remain.
memoryRef ID!
specUnresolvedReferencesPage SpecReferencePage! #3222 (#2213 S3, hrn:node:hadronmemory.com:specs:cor:api:120:04): specUnresolvedReferences as a page. Same read gate and refusals as specUnresolvedReferences, and the same list in the same order, so the pages concatenate to exactly what specUnresolvedReferences returns. total counts that whole list and hasMore says whether rows remain past this page. Default page 20, limit: 0 is count-only, a negative limit is 0, a limit over 200 is served as 200, a negative offset is 0. Paging bounds the response, not the work: each page still scans the whole corpus. memoryRef accepts the memory's ID or URN.
memoryRef ID!
limit Int
offset Int
appRun AppRun One run (cor:agt:010:02). ref is an AppRun ID or an hrn:apprun:<root>:<app>:<run-id> URN (#696). Readable by a platform admin, a READER of the run's organization, the run's own App key, or a user with a live App relationship for a run on their behalf or a MANUAL run they started. A run the caller may not read returns null, exactly like a missing one (#1577: no existence oracle).
ref ID!
latestAppRun AppRun The latest run of an App resolved to a concrete run (#696) — 'current/latest/previous' are queries, never magic run-ids in URN space (cor:urn:010:02). previous: true returns the run before the latest.
appRef String!
previous Boolean
appRuns AppRunsPage! The run audit list. statuses (#836) is a disjunction — 'everything still in flight' is [PENDING, RUNNING] and 'what went wrong' is [FAILED, TIMED_OUT], neither of which the single-valued status arg could express. Per conventions:multi-ref-scope-args: OMITTING it means no status filter, while an explicitly EMPTY list is the EMPTY scope and returns nothing - it never silently falls back to 'all'. Values are deduped; an unknown member is rejected by enum validation rather than dropped. status is DEPRECATED in favour of statuses but remains accepted. When statuses is non-null it wins, including an empty list; omitted or null statuses falls back to status. No removal date is promised here. sortBy / sortDir (#833) order the whole result set server-side, so a client table is no longer limited to sorting the page it happens to hold.
appRef String
orgRef String
status AppRunStatus

⚠️ DEPRECATED

Use statuses (#836) - a single value cannot express PENDING-or-RUNNING.
statuses [AppRunStatus!]
parentRunId ID
sortBy AppRunSortField
sortDir SortDirection
limit Int
offset Int
agentSchedules AgentSchedulesPage!
appRef String!
limit Int
offset Int
agentWebhooks AgentWebhooksPage!
appRef String!
limit Int
offset Int
actionTickets ActionTicketsPage! The ticket ledger: minted, consumed-by-which-run, expired (org-ADMIN).
orgRef String!
limit Int
offset Int
connectionGrant ConnectionGrant One connection grant the caller created, by ID; null if not theirs (no existence oracle).
ref ID!
connectionGrants ConnectionGrantsPage! The caller's own connection grants; connectionRef narrows to one connection.
connectionRef String
limit Int
offset Int
grant Grant One grant by id (#3789). Read only by a BOUND WORKER SESSION, in its own App, for a grant naming that worker directly, a pending one it requested itself, or (#3711) one held by its role agent in this App while the agent is installed and licensed here. Every other caller, a soft-deleted App and a missing id all answer null: no error and no existence oracle.
ref ID!
grants GrantsPage! The bound worker's own grants (#3789): the rows naming it directly as holder, the pending ones it requested, and (#3711) every row, in every state, held by its role agent in this App while that agent is installed and licensed here (never another App's, never a base agent's). Any other caller gets an empty page, never an error. limit 0 returns the count only.
limit Int
offset Int
myGrants GrantsPage! The caller's own grants across every App (#3800, hrn:node:hadronmemory.com:specs:cor:acl:140:05, ruling 0255 item 8): the rows naming the signed-in person directly as holder, in every state, newest first. Never another holder's, and never a row the person only issued or requested for someone else. Leaving an Org does not hide a grant. A soft-deleted App conceals its grants. There is no state label; allows is the one live function. An App key, a run, an impersonated session and a worker session get an empty page, never an error. limit 0 returns the count only.
limit Int
offset Int
appGrants GrantsPage! #3711 (hrn:node:hadronmemory.com:specs:cor:acl:140:05, ruling 0253 item 4): every grant of one App, in every state (pending, active, expired, spent, revoked, holder departed), newest first, for whoever manages the App as a person. It shows the whole record, including who revoked a grant, when its holder went and each signature's signer and passkey label, never a credential id or public key. Anyone else (a member who does not manage, an outsider, a worker session, an App key, a run, an impersonated session) and an unknown App get an empty page, never an error. limit 0 returns the count only.
appRef String!
limit Int
offset Int
grantActions GrantActionsPage! #3708 (hrn:node:hadronmemory.com:specs:cor:acl:140:02, ruling 0255 item 2): the registered actions, by name, for anyone in the named App: a participating person, or a bound worker session of that App. The App is named, never inferred. Every other caller (no credential, a non-participant, an unknown, malformed or deleted App, another App's or a retired worker, an App key, a headless run, an impersonated session even of a participant) gets an empty page, never an error. Read only; limit 0 returns the count only.
appRef String!
limit Int
offset Int
action GrantAction #3708: one registered action by its exact name, read under the same gate as grantActions. An unknown name and every refused caller answer null.
appRef String!
ref ID!
principalGrant PrincipalGrant One action grant by ID - visible to the grantee or an admin of its org; null otherwise (no existence oracle).
ref ID!
principalGrants PrincipalGrantsPage! Action grants. Default: the caller's own (self-audit is never gated). An org admin passing orgRef sees that org's grants, optionally narrowed by userRef.
orgRef String
userRef String
limit Int
offset Int
quotaCounters [QuotaCounter!]! Usage-vs-limit counters for an org (+ one app when appRef given). Org-ADMIN. Rows materialize on first view, seeded with platform defaults (#510).
orgRef String!
appRef String
effectiveActionPolicy EffectiveActionPolicy! Explain the standing policy chain (org / user / app) for one action - which layer denies it (#510, cor:acl:040:02). Org-ADMIN on the app's org.
appRef String!
action String!
userRef String
aiModelPrice AiModelPrice One provider rate row by id (spec 046). Authenticated read - rates are not a secret.
ref ID!
aiModelPrices AiModelPriceList! Provider rate rows, newest effective first, optional provider/model filter (spec 046). Authenticated read.
provider String
model String
tier Int
limit Int
offset Int
creditLedgerEntries CreditLedgerEntryList! One org's append-only credit-ledger page, newest first (spec 046). Org-ADMIN.
orgRef String!
limit Int
offset Int
creditBalance CreditBalance! One org's credit balance - SUM over the append-only ledger (spec 046). Org-ADMIN.
orgRef String!

Mutation

Field Argument Type Description
setReviewSchedule PrProtocolResult! #3448 — owner-chain only, never the assignee (hrn:node:hadronmemory.com:specs:cor:agt:050:09). Non-empty unique colon-separated atom slots, at most 64 characters each; latest event replaces the schedule. Dropping a current negative slot at the frozen head refuses REVIEW_SEAT_NOT_SUPERSEDABLE. All five protocol commands refuse finished/cancelled written tasks with TASK_ENDED after checking authority.
taskRef ID!
slots [String!]!
freezePullRequestHead PrProtocolResult! #3448 — the assignee freezes a full 40-hex head on a task with a pull_request reference (hrn:node:hadronmemory.com:specs:cor:agt:050:08). Any child seat's newest negative verdict at that SHA, including a superseded seat or dropped slot, refuses REVIEW_SEAT_NOT_SUPERSEDABLE: returning to an old head cannot erase a finding.
taskRef ID!
head String!
assignReviewSeat PrProtocolResult! #3448 — seat owner-chain binds a direct child to a scheduled slot at the frozen head. A current seat's CHANGES_REQUESTED, FAIL or REFUSED at this head prevents replacement, with or without supersedes, and a negative seat cannot move slots (REVIEW_SEAT_NOT_SUPERSEDABLE). A seat task is assigned once (REVIEW_SEAT_ALREADY_ASSIGNED); a replacement must name the current sibling in supersedes (REVIEW_SEAT_SUPERSEDES_REQUIRED). Checks and write hold the build row FOR UPDATE.
taskRef ID!
slot String!
head String!
supersedes ID
recordReviewVerdict PrProtocolResult! #3448 — STARTED seat's assignee records a verdict at its assigned head, without finishing it (hrn:node:hadronmemory.com:specs:cor:agt:050:08). REVIEW_SEAT_UNASSIGNED or REVIEW_HEAD_MISMATCH writes nothing. A different actor cannot overwrite a same-head negative verdict (REVIEW_SEAT_NOT_SUPERSEDABLE); its original actor may re-rate. #4235: the review.verdict event also carries reviewerFamily, reviewerModel and modelReportedAt, copied from the recording worker's session (its self-report, not verified), null where none is recorded or a person records it; no argument sets them and readiness never reads them (hrn:node:hadronmemory.com:specs:cor:agt:130:02).
taskRef ID!
head String!
verdict ReviewVerdict!
node String
receipt String
recordReadyCall PrProtocolResult! #3448 — build assignee records pr.ready only when every current scheduled seat is finished with APPROVE, PASS or CARRY at the frozen head. Its verdict actor must differ from both the build's current assignee and the newest pr.frozen actor; Worker/person identity stays distinct from holder credentials. PR_NOT_READY carries failing slots; event facts only, never opaque properties (hrn:node:hadronmemory.com:specs:cor:agt:050:28).
taskRef ID!
head String!
linkDefectToPullRequest DefectLink! #4280 (S12b; Proposed hrn:node:hadronmemory.com:specs:cor:agt:130:05) — record that a defect found after a pull request merged traces back to it: one review.defect-linked event on the PR's build task (prTaskRef, which needs a pull_request reference: PR_REFERENCE_MISSING). defectRef is the defect's issue URL, under the same rules as a task reference of kind issue, stored as given. introducedAtHead, when given, is a full 40-hex head frozen on that task (DEFECT_HEAD_NOT_FROZEN otherwise); the review-quality report counts the defect against approving reviews at that head or a later one. Who: a worker through its bound session whose current Worker.role is qa-engineer or coordinator, a person who manages the App, or a worker whose holder manages it, with an instruction. The App's key and a run may not. A caller who may not read the App is answered as for a task that does not exist (TASK_NOT_FOUND); one who may read it but not link gets DEFECT_LINK_FORBIDDEN, with nothing written. One link per (defect, task): linking the same pair again returns the existing link with created false and writes nothing. A retry is checked like a first call: an introducedAtHead that was never frozen is still refused DEFECT_HEAD_NOT_FROZEN, not answered with the existing link (#4286). A link never changes a verdict, a seat, readiness or the task.
defectRef String!
prTaskRef ID!
introducedAtHead String
instruction ActInstructionInput
setRateLimitPolicy RateLimitPolicy! Platform ADMIN/OWNER human only. Version-checked limits/mode edit, audit recorded; no counter reset (#1793).
input SetRateLimitPolicyInput!
restoreNode Node! Restore one retained deleted node in a live memory you can read and write. Restore deleted ancestors first; governed nodes, comments, compiled boot prompts and protected internal addresses refuse. Does not restore descendants or revisions. hrn:node:hadronmemory.com:specs:cor:acl:130:02
nodeRef ID!
reAdoptAutomation Boolean! #1719: rebind a trigger to its reviewed graph. expectedHash must match previewAutomation; edits since preview refuse adoption.
triggerKind AutomationTriggerKind!
triggerRef String!
expectedHash String!
approveAutomation Boolean! #2441: adopt the automation by the hash the adopter reviewed (automationApproval.hash). Same door as reAdoptAutomation: one APPROVE event per successful call, even when nothing changed. A changed automation answers AUTOMATION_CHANGED.
triggerKind AutomationTriggerKind!
triggerRef String!
expectedHash String!
declineAutomation Boolean! #2441: decline. An adopted trigger is revoked, so its next run fails AUTOMATION_UNADOPTED (REVOKE event); with nothing adopted it changes no state (DECLINE event). A MANUAL origin deletes its consent row. Runs already started keep their snapshot.
triggerKind AutomationTriggerKind!
triggerRef String!
setAppMemoryWriteGrant AppMemoryWriteGrant! #2484: let an App's userless runs create or update a node in one memory under one loc prefix (required; no memory-wide grant). The caller is a person acting as themselves who manages the App and can write the memory (person-only, hrn:node:hadronmemory.com:specs:cor:dmo:050:12, #3277). A shared memory must be one the App's own org or team space holds; a personal or private memory only by its owner, who must also manage the App; an encrypted memory is never grantable; nor is a system-class memory (#2710: an Agent's system memory, its boot-prompt source included, is written only by whoever manages the Agent, hrn:node:hadronmemory.com:specs:cor:agt:040:11), and a grant made on one before that rule authorizes no write. Granting the same prefix again returns the live grant. One content-free event is recorded. hrn:node:hadronmemory.com:specs:cor:agt:010:01
appRef String!
memoryRef String!
prefix String!
registerNodeUrn String
revokeAppMemoryWriteGrant AppMemoryWriteGrant! #2484: end a grant; the next write by the App's run is refused. Whoever manages the App may revoke, as themselves or through their held worker on a validated instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12 S6, ruling 0109 A; one team event, never the grant id). The row stays with its end time; revoking a revoked grant changes nothing and records nothing. hrn:node:hadronmemory.com:specs:cor:agt:010:01
id ID!
instruction ActInstructionInput
setAutomationTeamSnapshotGrant AutomationTeamSnapshotGrant! #3350: App managers, as people acting as themselves, give this live schedule/webhook a read-only own-App team snapshot grant, off until given; identical repeat returns the live row. hrn:node:hadronmemory.com:specs:cor:agt:050:23
appRef ID!
triggerKind String!
triggerId ID!
revokeAutomationTeamSnapshotGrant AutomationTeamSnapshotGrant! #3350: terminal revoke, App managers only. A held worker on a validated instruction may revoke within its own App; changing revokes record the worker and holder.
id ID!
instruction ActInstructionInput
setAutomationReadGrant AutomationReadGrant! #2883: give an automation (a live schedule or webhook of the App) a read grant on one memory or loc prefix. Given by whoever manages the target: the Agent for its system memory, the memory's manager otherwise, as a person (person-only, hrn:node:hadronmemory.com:specs:cor:dmo:050:12, #3277). A refusal is the same Forbidden as an unknown App, trigger or memory.
appRef String!
triggerKind String!
triggerId ID!
memoryRef String!
prefix String
revokeAutomationReadGrant AutomationReadGrant! #2883: end an automation read grant. The App's managers or the target's manager, as themselves or through a held worker on a validated instruction within its own App. Terminal, with no event on a repeat.
id ID!
instruction ActInstructionInput
createAgentTask AgentTask! #1705 — create an agent task (hrn:node:hadronmemory.com:specs:cor:agt:050:06 root, :07 child). Writes task.created, and task.assigned when an assignee is named. A worker acts through its session (X-Hadron-Session); a person acts as themselves. A root task's creator may name its owner at creation — any participating worker or person (#1757, hrn:node:hadronmemory.com:specs:cor:agt:050:01, ruled 2026-10-11). Typed refusals: TASK_NOT_FOUND (a parent the caller cannot read, or in another App), TASK_NOT_ASSIGNEE, TASK_ENDED, TASK_CHILD_OWNER_MISMATCH, TASK_OWNER_INVALID, TASK_ASSIGNEE_INVALID, SESSION_NOT_BOUND, APP_NOT_FOUND (an App that does not exist or that you do not participate in, alike), APP_UNINSTALLED, FORBIDDEN (impersonation), BAD_USER_INPUT. Every write re-checks the caller's participation and the App's state inside its transaction. #2198 (experiment): createAgentTask, assignAgentTask, reassignAgentTask and finishAgentTask may succeed WITH warnings, in the response's `extensions.warnings` (not in `errors`): a list of { path (the mutation's response key), code, text, register? }. Codes are a closed list per release (task.create.no-source, task.assign.assignee-unavailable, task.assign.assignee-busy, task.assign.assignee-paused, task.finish.open-children, from #3267 task.start.other-started, task.start.parent-ended (both on startAgentTask) and task.progress.children-ended (on recordAgentTaskProgress; other-started and children-ended, like the three assign facts, are filed only to a caller who may read the App's worker state), and from #2607 task.cancel.open-children on cancelAgentTask, alarm.ack.outside-chain on acknowledgeAlarm, and #2733 ticker.code.unmapped on createTicker); a client must tolerate unknown codes. `text` is fixed per code. `register` appears only for a caller that has an Agent: { state: mapped (taskLoc, taskUrn) | unmapped | unresolved | withheld }. #3491 (ruling 0176): the first three are given only when the caller may read every system memory on the chains looked up (the Team Agent's and the caller's own Agent's), as for every action answer (hrn:node:hadronmemory.com:specs:cor:agt:110:03); otherwise, or when the lookup fails or runs out of time, it is { state: withheld }, which says nothing about what the chains hold. A warning filed after the request has spent its whole read budget carries no register at all (nothing was looked up). A warning never blocks and never reveals another worker's state to a caller who could not already see it on the roster. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
input CreateAgentTaskInput!
instruction ActInstructionInput
recordAppAction RecordAppActionResult! #3449: App action app.<current-app-slug>.<name>, lower-case legal URN atom, at most 64 characters. Same creator authority as createAgentTask (hrn:node:hadronmemory.com:specs:cor:agt:050:06). taskRef must name a readable task in this App; unknown and foreign refs answer TASK_NOT_FOUND. An omitted payload becomes {}; explicit null, non-objects, NUL or an unpaired surrogate in a JSON key/value refuse BAD_USER_INPUT. payload is a JSON object of at most 4096 UTF-8 bytes, readable by EVERY App participant and the App's own key, with or without taskRef, and must contain nothing secret (hrn:node:hadronmemory.com:specs:cor:agt:050:23). Each successful call appends a new event (retries are not deduplicated), type = code, payload = {payload}. Task-bound actions are passive: they never acknowledge assignment/child-finished wakes. APP_ACTION_CODE_INVALID refuses invalid codes and foreign slugs. The register answer reads as the caller (hrn:node:hadronmemory.com:specs:cor:agt:110:03), never authorization. A caller without an Agent receives WITHHELD with code only, no task loc/URN and no register lookup.
appRef ID!
code String!
taskRef ID
payload JSON
createAgentTasks [AgentTask!]! Default matching (distinctAssignees omitted, null or false): items with match:true each get one post-commit match attempt in list order; failure marks that task, not a call refusal. Different workers and all-or-none matching are not requested. A match item blocked after all links refuses the whole call as BAD_USER_INPUT with its position, before any commit or attempt. #2653 (hrn:node:hadronmemory.com:specs:cor:agt:050:06, creating several at once; ruling 0011 A): create 1 to 25 tasks in the App appRef, all or none, in one transaction. Each task is judged exactly as createAgentTask judges it alone (the same gates, owner rules, refusals and warnings); the first refusal refuses the whole call, creates and records nothing, and carries extensions.position, the 1-based position of the task that caused it (tasks are judged one at a time in list order, each wholly before the next: its checks before the write, then its whole write, its blockers named by an existing task or by an earlier position included; last come the links to later positions, in list order). An empty list is BAD_USER_INPUT and more than 25 is TASK_BATCH_TOO_LARGE, before anything is created. A task names an existing parent, never another task of the call; a root task naming an App other than appRef is APP_NOT_FOUND, and a parent in another App TASK_NOT_FOUND. blockedByPositions names other tasks of the call as blockers (a self-block or a cycle is TASK_BLOCKER_CYCLE, a position outside the list BAD_USER_INPUT), and needs the same assigner authority as blockedBy. Handles follow list order and a refused call spends none. Each task records the events a single create records; all launches run only after the commit, and each task's warnings are filed under "<response key>.<position>". The result is every task, in list order. Not idempotent: nothing is deduplicated, so a caller that lost the answer lists the App's tasks before trying again. With distinctAssignees:true (hrn:node:hadronmemory.com:specs:cor:agt:050:06, ruling 0084 A), each task whose match is true is matched inside the same transaction, in list order, excluding every explicitly named worker in this call and every worker already matched. Each task keeps its own requirements; there is no global search or backtracking. After the normal create and blocker checks, any failed match refuses the whole call as TASK_MATCH_FAILED, with extensions.position (1-based) and extensions.reason (the single match's failure reason). No tasks, handles, events, failure marks or launches survive. Naming the same worker twice with this option is BAD_USER_INPUT at the second position. Named people and tasks not asking for a match keep their meaning.
appRef ID!
tasks [CreateAgentTasksItemInput!]!
distinctAssignees Boolean
claimUntrackedTaskItems ClaimUntrackedTaskItemsResult! #3125 S3 (hrn:node:hadronmemory.com:specs:cor:agt:120:03): claim up to limit (1 to 10, default 1) of the items untrackedTaskItems would list with the same filters, in its order. Each claim is a root task owned by and assigned to the caller, created STARTED with startedAt set, externalId and source the item's URL, an ISSUE reference to it, and the item's title (control characters removed, clipped to the title cap); it records task.created, task.assigned and task.started. Each claim commits on its own. An item another caller claimed first is skipped, so concurrent callers get disjoint sets. A refusal mid-walk stops it and is returned with the claims already made: incompleteReason claim_refused with its code in refusalCode (claim_failed, refusalCode null, for an unexpected failure after a claim). A person or a worker claims for themselves and names no assignee or owner (BAD_USER_INPUT if it does). #3132: the App's own key names the assignee (TASK_ASSIGNEE_REQUIRED) and the owner (TASK_OWNER_REQUIRED), each a worker of the App or a person who participates in it (TASK_ASSIGNEE_INVALID / TASK_OWNER_INVALID, as createAgentTask), all judged before any GitHub call; the task is started on the assignee's behalf, and its events name the key as actorAppKeyId and the assignee as their subject. A claim is the only task write an App key makes. A key request carrying a session is APP_KEY_SESSION_BOUND. Other refusals as untrackedTaskItems. #3422: noTeam as on untrackedTaskItems, applied before the claim walks the list: true claims only items carrying none of the integration's team labels, false or omitted keeps the current behaviour, and with team it is refused with BAD_USER_INPUT before GitHub is read and before any task is created.
appRef ID!
integration String!
team ID
noTeam Boolean
repository String
ready ReadyFilter
limit Int
assignee AgentTaskPartyInput
owner AgentTaskPartyInput
setAgentTaskPriority AgentTask! #2644 (hrn:node:hadronmemory.com:specs:cor:agt:050:01) — assigner authority; priority1..5, default1. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
taskRef ID!
priority Int!
instruction ActInstructionInput
addAgentTaskBlocker AgentTask! #2644 (hrn:node:hadronmemory.com:specs:cor:agt:050:02) — add a same-App blocker to a backlog/pending task, refusing cycles serially. Assigner authority. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
taskRef ID!
blockerTaskRef ID!
instruction ActInstructionInput
removeAgentTaskBlocker AgentTask! #2644 (hrn:node:hadronmemory.com:specs:cor:agt:050:02) — remove a blocker from a backlog/pending task. Last-blocker release restarts stall clocks and preserves status/assignee. Assigner authority. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
taskRef ID!
blockerTaskRef ID!
instruction ActInstructionInput
updateAgentTask AgentTask! #2645 — edit descriptive fields using assignment authority (Proposed Editing rule, hrn:node:hadronmemory.com:specs:cor:agt:050:09). Owner, reporting-chain coordinator or App manager; an assignee alone may write only properties (hrn:node:hadronmemory.com:specs:cor:agt:050:28) and references (#3441, ruling 0233); any other field it names refuses the whole call TASK_NOT_OWNER. Never an App key. Ended tasks refuse TASK_ENDED. Omitted fields stay unchanged; empty optional fields clear, tags/requirements replace whole. An edit is not progress and clears no wake. Source is fixed. Event carries changed field names only (hrn:node:hadronmemory.com:specs:cor:agt:050:11). #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
taskId ID!
input UpdateAgentTaskInput!
instruction ActInstructionInput
createTicker Ticker! #1747 — create a ticker in an App (hrn:node:hadronmemory.com:specs:cor:agt:080:01, :18). Any App participant, or a session bound to a worker of the App, up to the App live-ticker cap. The owner is the caller, never an argument. Refusals: TICKER_NAME_TAKEN, TICKER_CADENCE_OUT_OF_RANGE, TICKER_LIMIT_REACHED, TICKER_QUIET_HOURS_INVALID, APP_NOT_FOUND, APP_UNINSTALLED.
appRef String!
input TickerInput!
createAgentTickerTemplate AgentTickerTemplate! #2024 — declare a ticker on an Agent. Whoever may edit the Agent (ADMIN on it); an App manager is not thereby an Agent editor. Affects only FUTURE casts. Refusals: TICKER_TEMPLATE_NAME_TAKEN, TICKER_TEMPLATE_LIMIT_REACHED, TICKER_CADENCE_OUT_OF_RANGE, TICKER_QUIET_HOURS_INVALID, BAD_USER_INPUT (reasons), AGENT_NOT_FOUND, FORBIDDEN.
agentRef String!
input AgentTickerTemplateInput!
updateAgentTickerTemplate AgentTickerTemplate! #2024 — change a template; absent fields are unchanged. expectedRevision must be the revision you read, else TICKER_TEMPLATE_REVISION_MISMATCH and nothing is written. Affects only future casts.
id ID!
expectedRevision Int!
input AgentTickerTemplatePatch!
deleteAgentTickerTemplate Boolean! #2024 — remove a template (it stays as history; its name may be reused). expectedRevision as for update. Tickers already generated from it are untouched.
id ID!
expectedRevision Int!
updateTicker Ticker! #1747 — change a ticker. Its owner, the holder of its owning worker, or whoever manages the App. The slug never changes. #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
ref String!
input TickerPatch!
instruction ActInstructionInput
deleteTicker Boolean! #1747 — delete a ticker. Its live subscriptions end with reason TICKER_DELETED; its name may be reused, its slug never. #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
ref String!
instruction ActInstructionInput
setAppTickerSettings AppTickerSettings! #1747 — change an App ticker settings (hrn:node:hadronmemory.com:specs:cor:agt:080:05, :19). Whoever manages the App only. Refusals: TICKER_SETTINGS_OUT_OF_RANGE, TICKER_SETTINGS_CONFLICT (a floor above a live ticker cadence), DELIVERY_SETTINGS_CONFLICT (the shared cadence floor must keep stuckWindowSeconds greater than busyDelaySeconds + minCadenceSeconds). #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
appRef String!
input AppTickerSettingsInput!
instruction ActInstructionInput
setAppDeliverySettings AppDeliverySettings! App managers only; omitted preserves, null refuses. #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
appRef String!
input AppDeliverySettingsInput!
instruction ActInstructionInput
setTeamPause TeamPause! #2138: pause or resume the whole team, as whoever manages the App. Separate from each worker's own pause: a worker cannot lift it, and ending it clears no self-pause. While paused, no worker is nudged and every worker's check status is PENDING (TEAM_PAUSED). #4223: while paused, the platform issues no worker.start for an assignment; lifting the pause starts the held workers with no open session whose tasks were assigned during it, and no others. #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
appRef String!
paused Boolean!
instruction ActInstructionInput
setAppSweepMode AppSweepMode! #4224 (S3 of #4229) — set the App's sweep mode, as whoever manages the App. OFF (the default) restores today's behaviour in one write: every hostDesiredState row then says SWEEP_OFF and a sweep acts on nothing. A change is one team.sweep-mode-changed team event (from, to); setting the mode it already has changes and records nothing. Refusals: FORBIDDEN (not a manager; an App key never is). The App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
appRef String!
mode SweepMode!
instruction ActInstructionInput
setWorkerLeaveAlone WorkerLeaveAlone! #4224 (S3 of #4229) — mark a worker leave-alone, or clear the marker, as whoever manages the App. A marked worker's hostDesiredState row says LEAVE_ALONE: a sweep observes and reports it and never starts, stops or repairs it. A change of the marker is one worker.leave-alone-changed team event (the new value only, never the reason); a call that changes nothing records nothing. Marking an already marked worker with another reason replaces the reason, who set it and when. Refusals: WORKER_NOT_FOUND (also for a caller who is not a participant of the worker's App), WORKER_LEAVE_ALONE_NOT_PERMITTED (a participant who does not manage the App; a worker's session without an instruction), WORKER_RETIRED, BAD_USER_INPUT (a reason on a clear, or one over 500 characters). The App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
input SetWorkerLeaveAloneInput!
instruction ActInstructionInput
setAppProperties App! #3125 S1 (hrn:node:hadronmemory.com:specs:cor:dmo:050:20) — replace the App's properties with this JSON object; null or an empty object clears them. Whoever manages the App only: as themselves, or through their held worker's session on an instruction (a worker with none, an App key, a run and an impersonation are refused). Never put a secret here. When expectedRevision is sent it must equal App.propertiesRevision. A write that changes nothing changes no revision and records no event; a changing write records app.properties-changed naming the changed top-level keys, never values. Bounds: 16 KiB of JSON, 64 levels. The taskIntegrations key (hrn:node:hadronmemory.com:specs:cor:agt:120:01) is validated: a list of { name, provider: "github", repositories: ["owner/name"], readyLabel?, excludeLabels?, teams?: [{ lead, label }] }, where lead is a worker of this App (URN, id or name). Refusals: FORBIDDEN, PROPERTIES_NOT_AN_OBJECT, PROPERTIES_TOO_LARGE, PROPERTIES_KEY_RESERVED (a key named __proto__ at any depth, which cannot be stored; names the path), TASK_INTEGRATION_INVALID (names the JSON path, never the value), APP_PROPERTIES_CONFLICT. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
appRef String!
properties JSON
expectedRevision Int
instruction ActInstructionInput
setAppChatbotAiConfig App! #3957 (hrn:node:hadronmemory.com:specs:cor:dmo:050:10, hrn:node:hadronmemory.com:specs:cor:dmo:050:12): set (configId) or clear (null) the App's chatbot AI config. Whoever manages the App, a platform admin included even on a user-owned App: choosing a config reads, sets and tests no key. A person acting as themselves. configId must be one of THIS App's own configs; another App's, a deleted one and an unknown id all get the same AiServiceConfigNotFoundError. A disabled own config is accepted and skipped at turn time until it is enabled again.
appRef ID!
configId ID
setTeamStopSignal StopSignal! #2022 (hrn:node:hadronmemory.com:specs:cor:agt:090:01, :06) — set a stop signal. Whoever manages the App: any level and scope. A host key: a HALT on its own host only. Never replaces another signal. Refusals: APP_MANAGER_REQUIRED, HOST_SCOPE_REQUIRED, STOP_SIGNAL_SCOPE_FORBIDDEN, STOP_SIGNAL_NOT_FOUND (the target), BAD_USER_INPUT, APP_NOT_FOUND. #2173/#2169 (R95): setting ANY signal is refused with STOP_SIGNAL_UNAVAILABLE while a worker it would cover is on a lane with no fresh stop-consumer declaration (a worker would be stopped without being told; the extensions name the worker count and the lanes). A consumer declares a lane by polling dueWakes with accepts: [STOP]. Lifting and listing are unaffected. #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
input SetTeamStopSignalInput!
instruction ActInstructionInput
liftTeamStopSignal LiftStopSignalResult! #2022 (hrn:node:hadronmemory.com:specs:cor:agt:090:05, :06) — lift a stop signal. Whoever manages the App, any; a host key, a HALT on its own host. Lifting one never ends another. changed is false when it had already ended. Refusals as setTeamStopSignal. #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
appRef String!
id ID!
instruction ActInstructionInput
subscribeWorker SubscribeResult! #1747 — subscribe a worker to a ticker (hrn:node:hadronmemory.com:specs:cor:agt:080:20, :25). Its holder and whoever manages the App, to any ticker; the worker itself only at or slower than the App self-subscription cadence (SUBSCRIBE_CADENCE_NEEDS_HOLDER); a worker holding the may-subscribe-workers grant, with a person behind the call, for OTHER workers only. Idempotent for a live subscription. A grant use is announced to the team chat, best-effort: announcement says POSTED or FAILED, and the subscription stands either way. #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only. #4234: a worker of a SHORT_LIVED Agent is refused TICKER_ON_SHORT_LIVED, after authorization and before anything is written (it runs only while it holds a task, so a ticker could not wake it). The refusal comes before the idempotent answer: re-subscribing such a worker that already has a live subscription is refused too, not answered changed false. Unsubscribing it stays allowed.
tickerRef String!
workerRef String!
instruction ActInstructionInput
applyAgentTickerTemplates ApplyAgentTickerTemplatesResult! #2096 — apply the Agent's current ticker templates to ONE existing worker (the repair for workers cast before the templates existed; hrn:node:hadronmemory.com:specs:cor:agt:080:33, :20). Whoever manages the App: not the worker on its own, not its holder as such, not a reportsTo chain. Creates only the template tickers the worker is missing, each owned by and subscribed to it, and never edits or deletes any existing ticker or subscription; a template the worker already has a live ticker for is reported under alreadyPresent and left as it is. A template below the App's cadence floor is created at the floor; if the App's live-ticker cap cannot take every missing ticker, or a generated name is already a live ticker's, the whole call is refused and nothing is created. Never automatic, never across workers. #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
workerRef String!
instruction ActInstructionInput
unsubscribeWorker SubscribeResult! #1747 — end a worker subscription. The same callers as subscribeWorker, and the worker itself, always. #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
tickerRef String!
workerRef String!
instruction ActInstructionInput
setWorkerWakeSettings WorkerWakeSettings! #1747 — change a worker wake settings (hrn:node:hadronmemory.com:specs:cor:agt:080:03, :21): the worker itself, its holder, or whoever manages the App, in either direction. Never the may-subscribe-workers grant. #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
workerRef String!
input WorkerWakeSettingsInput!
instruction ActInstructionInput
acknowledgeWakes AcknowledgeWakesResult! #1748 — record that wakes were delivered (hrn:node:hadronmemory.com:specs:cor:agt:080:16). Never moves a read position.
proofs [String!]!
acknowledgeDeliveryBatches AcknowledgeWakesResult! #2017 (S1) — record that delivery batches were typed (hrn:node:hadronmemory.com:specs:cor:agt:080:16, :17). Only the receiving host key or the worker's own receiving live session, within 15 minutes. The delivered mark rises to the end of each rendered range; with through (one batch only), only the listed channels move, each to a rendered seq of its own. Writes no read position, tick or budget. A repeat changes nothing.
batchIds [String!]!
through [BatchThrough!]
registerHost HostRegistration! #1709 — a host registers, or refreshes, which of its App's workers it can launch, as which model family, and in which worktrees it declares (hrn:node:hadronmemory.com:specs:cor:agt:070:01). The server validates their tokens, not filesystem existence. A host key only: an App key holding host:operate, which names the host; the request names none (hrn:node:hadronmemory.com:specs:cor:agt:070:04). Refreshing within the App's lapse count of poll intervals keeps it live. Refused HOST_KEY_REQUIRED for anyone else, APP_KEY_SCOPE_REQUIRED without the scope, APP_KEY_SESSION_BOUND with a session, BAD_HOST_REGISTRATION for a bad shape or a worker not of the App. #4222: while the App's hostSetupSource is SERVER, a listed worker the platform did not assign to this host is left out and reported in refusedWorkers (HOST_WORKER_NOT_ASSIGNED) instead; the registration still succeeds.
input RegisterHostInput!
assignHostWorker HostWorkerAssignment! #4222 — assign a worker to a host of its App: the workdir it runs in there, and its launcher profile (#4230: family, and optionally model, effort and accountProfile; hrn:node:hadronmemory.com:specs:cor:agt:070:01, the change Proposed). Whoever manages the App (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), or a held worker on its holder's instruction; never an App key. A worker may be assigned to several hosts. The assignment is a record until the App's hostSetupSource is SERVER. Refused BAD_HOST_ASSIGNMENT_ARGS (a workdir or host id that is not its token shape: a path, an option, a command), BAD_LAUNCHER_PROFILE (a family no host has a launcher for, or a model, effort or accountProfile that is not a profile token), HOST_ASSIGNMENT_NOT_PERMITTED, WORKER_NOT_FOUND, WORKER_RETIRED, and HOST_ASSIGNMENT_EXISTS when this worker is already assigned to that host and replace is not set. A refusal writes nothing.
input AssignHostWorkerInput!
instruction ActInstructionInput
unassignHostWorker Boolean! #4222 — remove a worker's assignment to a host. Whoever manages the App, as for assignHostWorker (HOST_ASSIGNMENT_NOT_PERMITTED otherwise). True when one was removed, false when there was none; a retired worker's assignment is removable.
input UnassignHostWorkerInput!
instruction ActInstructionInput
setHostSetupSource HostSetupSource! #4222 — set who states which workers the App's hosts run: HOST (the default) or SERVER. Whoever manages the App (HOST_ASSIGNMENT_NOT_PERMITTED otherwise). Under SERVER, registerHost accepts only the workers assigned to that host and reports the rest per row as HOST_WORKER_NOT_ASSIGNED in refusedWorkers, never failing the registration; a worker is started only on a host it is assigned to whose registration lists the assigned workdir, in that workdir and as the assigned family; with none, nothing is issued and the task waits (hrn:node:hadronmemory.com:specs:cor:agt:070:08). Takes effect at the next registration and start decision.
appRef String!
source HostSetupSource!
instruction ActInstructionInput
collectHostOperations [HostOperation!]! #1709 — a host collects its own operations, oldest first: those still ISSUED (now marked COLLECTED) and those it collected and has not reported, except a worker.start whose launch grant is still live (#1928: a re-collection never revokes a launch in flight). Only its own host's, in its own App (hrn:node:hadronmemory.com:specs:cor:agt:070:04). first: at most 200, default 20.
appRef String!
first Int
reportHostOperation HostOperation! #1709 — a host reports an operation's final outcome: SUCCEEDED, or FAILED with a reason (hrn:node:hadronmemory.com:specs:cor:agt:070:03). Only after collecting it, and only its own host's (another's is HOST_OPERATION_NOT_FOUND). The same outcome again answers the operation as it is; a different one is HOST_OPERATION_ALREADY_REPORTED. Writes host.operation.succeeded or host.operation.failed. #4062: HOST_OPERATION_ALREADY_REPORTED carries the operation id in extensions.id and the outcome already recorded in extensions.status, as a HostOperationStatus value (SUCCEEDED or FAILED); read the outcome there, not from the message. #3309 (hrn:node:hadronmemory.com:specs:cor:agt:050:27 part 11): a worker.reset-context failure may name HOST_UNSUPPORTED, optionally followed by ": " and detail, only before its claim (phase requested). After the claim this reason is BAD_CONTEXT_RESET_INPUT; its message lists the reasons accepted at that phase. #4292: an end-session operation FAILED with a reason whose leading code is AGENT_ABSENT ends the session when endAgentlessSession's conditions hold, and reads SUCCEEDED, writing no handoff; otherwise it stays FAILED, the session open.
input ReportHostOperationInput!
endAgentlessSession AgentlessSessionEnd! #4292 — a host ends an open session of a SHORT_LIVED worker it runs, after proving that no agent runs in the worker's worktree (reason AGENT_ABSENT); the backstop when the platform's worker.end never came or already failed (hrn:node:hadronmemory.com:specs:cor:agt:050:10, Proposed). A worker.end reported FAILED with a failureReason whose leading code is AGENT_ABSENT runs the same check and, when it holds, ends the session and reads SUCCEEDED. Refusals: HOST_DOES_NOT_RUN_WORKER (this host's registration does not list the worker, or under a server-held setup it is not assigned there, or the session runs on another host: a host-launched session is ended only by its launch host, a hand-started one only by the worker's sole live registration), SESSION_NOT_WORKERS, WORKER_NOT_SHORT_LIVED, WORKER_HAS_OPEN_TASK (the worker is the assignee of a PENDING or STARTED task; extensions.taskId names it). A session that already ended answers ended: false and writes nothing. The end is recorded with endReason agent_absent; it writes no handoff, and handoff in the result is true only when one the worker wrote before it exited names the session.
input EndAgentlessSessionInput!
setHostWorkerAvailability WorkerAvailability! #1709 — a host marks a worker it registers UNAVAILABLE, only as OUT_OF_TOKENS or HOST_DOWN, or clears a mark it set itself (hrn:node:hadronmemory.com:specs:cor:agt:060:08). It never replaces or clears anyone else's mark, a stall among them: AVAILABILITY_NOT_PERMITTED.
input SetHostWorkerAvailabilityInput!
setHostWorkerTerminals SetHostWorkerTerminalsResult! #2771 (proposed hrn:node:hadronmemory.com:specs:cor:agt:070:09) — a host reports the terminal state of workers it registers, as classified by its on-host sweep. The server builds what it stores (Worker.terminal): the host comes from the key and its registration, the time from the server, and no screen text of any kind is accepted. A malformed input refuses the whole call and stores nothing (BAD_USER_INPUT); a worker this host does not register is refused for that item only (WORKER_NOT_FOUND, as setHostWorkerAvailability); an older report than the stored one is skipped (TERMINAL_REPORT_STALE). The result lists the stored items and the refused items, each refusal with a reason. The report decides nothing: it feeds no check status, availability, matcher, stall rule or alarm.
input SetHostWorkerTerminalsInput!
recordHostSweepRun HostSweepRun! #4233 (S10 of #4229) — a host records one run of its sweep. The host key only (HOST_KEY_REQUIRED otherwise); the host is the key's own. The whole report is validated first and a malformed one stores nothing (BAD_USER_INPUT): a mode of OBSERVE or APPLY, counts from 0, at most 50 lines of worker token, outcome and reason code, and no free text. The same runId for the same host is the same run: a replay returns it and changes nothing. A run that applied or failed something produces ONE summary post in the App's team chat, from the platform, and a run that changed nothing posts nothing. Recording a run ends the host's stale-sweep alarm episode.
input RecordHostSweepRunInput!
issueHostOperation HostOperation! #1709 — issue an operation to one of the App's registered hosts (hrn:node:hadronmemory.com:specs:cor:agt:070:05). A type outside the closed set is HOST_OPERATION_TYPE_UNKNOWN (hrn:node:hadronmemory.com:specs:cor:agt:070:03), a missing, extra or malformed argument BAD_HOST_OPERATION_ARGS. worktree.create and worktree.remove: the worker's holder, the worker it reports to directly (not further up the chain), or whoever manages the App (else HOST_OPERATION_NOT_PERMITTED). worker.start: whoever manages the App only, with an optional taskId, for a held worker with no live session and no start in flight, in a worktree and family the live host registers for it (WORKER_NOT_HELD, WORKER_LIVE, WORKER_START_PENDING). worker.end: whoever manages the App only (else HOST_OPERATION_NOT_PERMITTED), naming an open session of the worker on a host that registers it (else BAD_HOST_OPERATION_ARGS). worker.deliver is the one type not issued yet, HOST_OPERATION_NOT_ISSUABLE until a host has a delivery path for it (hadron-cli#829). worker.reset-context is HOST_OPERATION_NOT_ISSUABLE here: the platform issues it when a task ends (#2162). An App key issues nothing (FORBIDDEN). An unregistered host is HOST_NOT_FOUND. #3321: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
input IssueHostOperationInput!
instruction ActInstructionInput
claimContextReset ContextResetStep! #2162 — a context reset's protocol (hrn:node:hadronmemory.com:specs:cor:agt:050:27), for the host its worker.reset-context operation was issued to, with that host's key only, after collecting the operation (HOST_OPERATION_NOT_COLLECTED otherwise). Each step names the reset and its epoch (STALE_EPOCH when it moved), is idempotent (a replay answers replayed: true), and is out of order CONTEXT_RESET_WRONG_PHASE. Another App's or host's reset is CONTEXT_RESET_NOT_FOUND. The final outcome is reported with reportHostOperation: SUCCEEDED once relaunched, or FAILED with a reason that starts with its code. claimContextReset takes the fence: the worker becomes unavailable RESETTING, or the reset is refused SESSION_CHANGED, OTHER_WORK, UNAVAILABLE, PAUSED, SETTING_OFF or WORKER_GONE.
input ClaimContextResetInput!
registerContextResetRecovery ContextResetStep! #3276 / ruling 0090 A, hrn:node:hadronmemory.com:specs:cor:agt:050:27 part 3 and hrn:node:hadronmemory.com:specs:cor:agt:070:04: register a live checkpointNode or atomically write checkpoint, exactly one. Host key only; generic node writes stay refused. Refusal order: CONTEXT_RESET_NOT_FOUND, HOST_OPERATION_NOT_COLLECTED, STALE_EPOCH, CONTEXT_RESET_WRONG_PHASE, CLAIM_LAPSED, RECOVERY_REF_INVALID, CHECKPOINT_MEMORY_ENCRYPTED, CHECKPOINT_LOC_TAKEN. Replay of registered non-ended phases returns the stored node without writing, even if checkpoint differs. DB UTC stamp: sheds:auto-YYYY-MM-DDTHHMMSSZ (seconds); occupied live or deleted address refuses with phase still claimed, no suffix/overwrite/parent/edge. Encrypted memory refused.
input RegisterContextResetRecoveryInput!
authorizeContextResetStop ContextResetStep! #2162 — the single stop grant per claim; a replay returns the same grant. The host signals only within stopLeaseMs of the moment it SENT this request (CLOCK_BOOTTIME). Refused NO_RECOVERY_REF, CLAIM_LAPSED, PROCESS_CHANGED or NOT_IDLE.
input AuthorizeContextResetStopInput!
reportContextResetAgentStopped ContextResetStep! #2162 / #3255 (hrn:node:hadronmemory.com:specs:cor:agt:050:27): the old agent stopped; its resetting mark now lasts until the relaunched agent's first activity. Optional lateStopMs records the host's late signal once. For an ended reset, a positive annotation from the collected host holding its stop-grant epoch records telemetry only and changes no reset, task, outcome, availability or alarm state.
input ContextResetStepInput!
reportContextResetRelaunched ContextResetStep! #2162 — the agent was relaunched under its wrapper.
input ReportContextResetRelaunchedInput!
reportContextResetRelaunchFailed ContextResetStep! #2162 — a failure after the claim that the host saw; the reset ends and the mark is released.
input ReportContextResetRelaunchFailedInput!
grantApp AppGrant! #1747 — give a worker a named App grant (hrn:node:hadronmemory.com:specs:cor:agt:080:24). Whoever manages the App only. Idempotent. Person-only (hrn:node:hadronmemory.com:specs:cor:dmo:050:12, #3277): never a worker session (a worker never gives a grant to itself) in any shape, a run principal, an impersonation or an App key, even when the worker's holder manages the App.
appRef String!
workerRef String!
name AppGrantName!
revokeAppGrant AppGrant! #1747 — revoke a grant. Whoever manages the App, as themselves, or through their held worker on a validated instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12 S6, ruling 0109 A); an admitted instructed revoke records one team event (never the grant id). Takes effect at the grantee next call.
appRef String!
workerRef String!
name AppGrantName!
instruction ActInstructionInput
assignAgentTask AgentTask! #1705 — assign a task with no assignee — a queued task (pending) or a BACKLOG task: the task's owner, a worker the owner reports to, directly or up the reportsTo chain, or whoever manages the App (hrn:node:hadronmemory.com:specs:cor:agt:050:09). closeSessionWhenDone, when given, replaces the task's value; omitted, the stored value is kept. Assigning a BACKLOG task moves it to pending (hrn:node:hadronmemory.com:specs:cor:agt:050:02, #1754). Refusals: TASK_NOT_FOUND, TASK_NOT_OWNER, TASK_ENDED, TASK_INVALID_TRANSITION (already assigned: use reassignAgentTask), TASK_ASSIGNEE_INVALID, SESSION_NOT_BOUND, APP_UNINSTALLED. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
taskId ID!
assignee AgentTaskPartyInput!
closeSessionWhenDone Boolean
instruction ActInstructionInput
reassignAgentTask AgentTask! #1705 — move a task to another assignee: the task's owner, a worker the owner reports to, directly or up the reportsTo chain, or whoever manages the App (hrn:node:hadronmemory.com:specs:cor:agt:050:09). A started task stays started; the former assignee can no longer move it. Refusals: TASK_NOT_FOUND, TASK_NOT_OWNER, TASK_ENDED, TASK_INVALID_TRANSITION (no assignee yet, or the same one), TASK_ASSIGNEE_INVALID, SESSION_NOT_BOUND, APP_UNINSTALLED. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
taskId ID!
assignee AgentTaskPartyInput!
closeSessionWhenDone Boolean
instruction ActInstructionInput
startAgentTask AgentTask! #1705 — start a pending task: its assignee only (hrn:node:hadronmemory.com:specs:cor:agt:050:08). #3267: may succeed with warnings, in extensions.warnings (see the experiment note on createAgentTask). Refusals: TASK_NOT_FOUND, TASK_NOT_ASSIGNEE, TASK_ENDED, TASK_INVALID_TRANSITION, SESSION_NOT_BOUND, APP_UNINSTALLED.
taskId ID!
recordAgentTaskProgress AgentTask! #1705 — record progress on a started task: its assignee only (hrn:node:hadronmemory.com:specs:cor:agt:050:08). Carries no text. #3267: may succeed with a warning, as startAgentTask does. Refusals as startAgentTask.
taskId ID!
disposeAgentTaskFinding AgentTask! #2663: finished tasks only, their assigners only; never an App key or impersonation. Records a new disposition value, never clears it; omitted/null reference means no reference on the new value. Unknown finding TASK_FINDING_NOT_FOUND; open task TASK_NOT_FINISHED; non-assigner TASK_NOT_OWNER; unreadable task TASK_NOT_FOUND; result unchanged (hrn:node:hadronmemory.com:specs:cor:agt:050:30). #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
taskRef ID!
findingId String!
disposition AgentTaskFindingDispositionCode!
reference AgentTaskReferenceInput
instruction ActInstructionInput
finishAgentTask AgentTask! #1705 — finish a started task with its result: its assignee only (hrn:node:hadronmemory.com:specs:cor:agt:050:08). A pending task is refused: start it first. Refusals as startAgentTask, plus BAD_USER_INPUT for an outcome that is not one word. #2652 (outcome set, hrn:node:hadronmemory.com:specs:cor:agt:050:30): a team may close the outcomes its tasks finish with, as the node schema:task-outcomes in the Team Agent's system memory, found through its base chain, with data {"outcomes": [...]} holding 1 to 100 one-word outcomes. With a set, an outcome outside it (matched exactly, case-sensitive) is TASK_OUTCOME_NOT_IN_SET, and the refusal does not list the set. A set that exists but is malformed, or two installed Team Agents when either carries the node, is TASK_OUTCOME_SET_UNUSABLE, refusing every finish. Both are judged after the assignee and status checks and before any write or event: the task stays started. With no set, any one word is accepted. The set is read only at finish.
taskId ID!
result AgentTaskResultInput!
cancelAgentTask AgentTask! #1705 — cancel a pending, started or backlog task: its owner, a worker the owner reports to, directly or up the reportsTo chain, or whoever manages the App (hrn:node:hadronmemory.com:specs:cor:agt:050:09; a backlog task directly, Holger team chat #8150). Refusals: TASK_NOT_FOUND, TASK_NOT_OWNER, TASK_ENDED, SESSION_NOT_BOUND, APP_UNINSTALLED. #2607 (experiment): a cancel that leaves pending or started children succeeds with the warning task.cancel.open-children in `extensions.warnings` (see createAgentTask); it does not end them. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
taskId ID!
instruction ActInstructionInput
releaseAgentTaskExternalId AgentTask! #4084 (hrn:node:hadronmemory.com:specs:cor:agt:120:02; who may release is Proposed, V87) — give a task's outside item back: clear its externalId so the next create naming it claims it. Whoever may cancel the task may release it (hrn:node:hadronmemory.com:specs:cor:agt:050:09), in any status; the assignee alone may not. Refused like a cancel: TASK_NOT_FOUND (a task you cannot read reads as absent), TASK_NOT_OWNER, APP_UNINSTALLED; then TASK_EXTERNAL_ID_NONE when the task holds no external id (a second release included). Nothing else about the task changes, and a refusal writes nothing. One task.external-id-released team event names the released id. The id is never set again on this task. #3323's instruction arm applies as on cancelAgentTask.
taskId ID!
instruction ActInstructionInput
handBackAgentTask AgentTask! #2651 — hand a started task back: its assignee only (hrn:node:hadronmemory.com:specs:cor:agt:050:29). The task loses its assignee, goes back to PENDING and is queued again (hrn:node:hadronmemory.com:specs:cor:agt:050:03); a returning worker is added to requirements.excludeWorkerIds, so the platform's matcher assigns it to another matching worker (hrn:node:hadronmemory.com:specs:cor:agt:060:06), and whoever may assign the task can remove that exclusion. A person who hands a task back is not added. One task.handed-back event carries the code only; no result is written; child tasks are untouched; every ordinary stall episode the task had ends, while a finish-by episode is kept until the task ends or its finish-by time is edited (hrn:node:hadronmemory.com:specs:cor:agt:050:13). taskRef is the task's id or handle. Refusals: TASK_NOT_FOUND, TASK_NOT_ASSIGNEE (anyone else, or a task with no assignee), TASK_ENDED (finished or cancelled), TASK_INVALID_TRANSITION (pending), BAD_USER_INPUT (a code outside the set, or text over 2,000 characters), SESSION_NOT_BOUND, APP_UNINSTALLED. Nothing changes on a refusal.
taskRef ID!
reason AgentTaskHandBackInput!
parkAgentTask AgentTask! #1754 — park a queued task in the backlog (hrn:node:hadronmemory.com:specs:cor:agt:050:02): pending with no assignee becomes BACKLOG — unassigned, never matched, never waited on, no alarms. Whoever may assign a task may park it: its owner, a worker the owner reports to, directly or up the reportsTo chain, or whoever manages the App (hrn:node:hadronmemory.com:specs:cor:agt:050:09). Refusals: TASK_NOT_FOUND, TASK_NOT_OWNER, TASK_ENDED, TASK_INVALID_TRANSITION (not pending, or an assignee), SESSION_NOT_BOUND, APP_UNINSTALLED. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
taskId ID!
instruction ActInstructionInput
cloneAgentTask AgentTask! #2646 (hrn:node:hadronmemory.com:specs:cor:agt:050:02, What a clone does): make a NEW task from an existing one, in its App, linked to it (clonedFrom / clones). A clone is a create: whoever may read the source and create a task there may clone it, in any status; the source is never changed and an ended task is never reopened. Copied: title, description, source, tags, requirements, references, closeSessionWhenDone, priority, properties and the parent. Not copied: assignee, status, result, handle, blockers, startBy, finishBy, externalId. The clone is PENDING (or BACKLOG, as input.status asks). The parent is kept only for someone who may create a child of it (else TASK_NOT_ASSIGNEE, nothing created, unless input.parentTaskId names another parent or null for none); a root is cloned as a root of the same kind, through the root create gate; under an ended parent it goes under the project AT0. The properties and priority are copied only for a caller who may set them and are otherwise left out, with no refusal. Refusals: TASK_NOT_FOUND (an unknown, unreadable or cross-App source or parent), BAD_USER_INPUT (AT0 cannot be cloned), TASK_NOT_ASSIGNEE, TASK_NOT_OWNER (a priority you name and may not set), TASK_ENDED (a named parent that has ended).
taskId ID!
input CloneAgentTaskInput
makeAgentTaskReady AgentTask! #1754 — make a backlog task ready to be worked (hrn:node:hadronmemory.com:specs:cor:agt:050:02): BACKLOG becomes PENDING and the task enters the queue. Clears any match failure and held-back match reservation; regular matching resumes, without a second match-now attempt. Whoever may assign a task may make it ready: its owner, a worker the owner reports to, directly or up the reportsTo chain, or whoever manages the App (hrn:node:hadronmemory.com:specs:cor:agt:050:09). Refusals: TASK_NOT_FOUND, TASK_NOT_OWNER, TASK_ENDED, TASK_INVALID_TRANSITION (not backlog), SESSION_NOT_BOUND, APP_UNINSTALLED. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
taskId ID!
instruction ActInstructionInput
acknowledgeAlarm AgentTeamEvent! #1706 — acknowledge an alarm (hrn:node:hadronmemory.com:specs:cor:agt:050:20): it stops waking higher owners; the stall episode goes on until the task moves. Any owner in the alarm's chain, or whoever manages the App (hrn:node:hadronmemory.com:specs:cor:agt:050:24), and nobody else; the time is the server's. Refusals: ALARM_NOT_FOUND (also for an App you cannot read), NOT_AN_ALARM, ALARM_NOT_IN_CHAIN, ALARM_ALREADY_ACKNOWLEDGED (the first stands), SESSION_NOT_BOUND, APP_UNINSTALLED. #2607 (experiment): an acknowledgement by a manager of the App who is no owner in the chain succeeds with the warning alarm.ack.outside-chain in `extensions.warnings` (see createAgentTask). #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
eventId ID!
instruction ActInstructionInput
setWorkerAvailability WorkerAvailability! #1706 — set a worker's availability for work (hrn:node:hadronmemory.com:specs:cor:agt:060:08): the worker itself, acting through its session, and only to UNAVAILABLE; the person holding its name; or whoever manages the App. A worker another reports to directly may also clear only a stall-rule unavailable mark (the stall rule must have set it), never set another worker unavailable. Writes availability.changed. Refusals: WORKER_NOT_FOUND, AVAILABILITY_NOT_PERMITTED, WORKER_RETIRED, BAD_USER_INPUT, SESSION_NOT_BOUND, APP_UNINSTALLED. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
input SetWorkerAvailabilityInput!
instruction ActInstructionInput
setModelFamilyAvailability ModelFamilyAvailability! #1706 — set a model family's availability for work in an App (hrn:node:hadronmemory.com:specs:cor:agt:060:09): whoever manages the App only. Writes availability.changed. Refusals: APP_NOT_FOUND, AVAILABILITY_NOT_PERMITTED, BAD_USER_INPUT, SESSION_NOT_BOUND, APP_UNINSTALLED. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
input SetModelFamilyAvailabilityInput!
instruction ActInstructionInput
setAgentTaskStallSchedule AgentTaskStallSchedule! #1706 — set an App's stall windows, and (#1763) its host-registration lapse: whoever manages the App. Refusals: APP_NOT_FOUND, APP_MANAGER_REQUIRED, BAD_USER_INPUT, SESSION_NOT_BOUND, APP_UNINSTALLED. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
appRef ID!
input AgentTaskStallScheduleInput!
instruction ActInstructionInput
setAgentModelGroup ModelGroup! #2831 S1 (hrn:node:hadronmemory.com:specs:cor:agt:060:12) - set an Agent's model group: the name is created or its whole pattern list replaced (no merge). Patterns are lowercase globs matched against a session's self-reported model (* any run, ? one character); an empty list is allowed. Whoever manages the Agent only. A group only steers matching, never authorization. Refusals: AGENT_NOT_FOUND, FORBIDDEN, BAD_USER_INPUT, MODEL_GROUP_LIMIT_REACHED, AGENT_OWNERSHIP_CHANGED.
agentRef ID!
name String!
patterns [String!]!
deleteAgentModelGroup Boolean! #2831 S1 - remove an Agent's model group. Installs that override it keep their own list. Whoever manages the Agent only. Refusals: AGENT_NOT_FOUND, FORBIDDEN, BAD_USER_INPUT, MODEL_GROUP_NOT_FOUND, AGENT_OWNERSHIP_CHANGED.
agentRef ID!
name String!
setAppModelGroup ModelGroup! #2831 S1 (hrn:node:hadronmemory.com:specs:cor:agt:060:12) - set an App's model group of this name: it overrides the Team Agent's group of that name (replacing its whole list, no merge) or, when the Agent has none, is the App's own. An empty list matches no one. Whoever manages the App only. Refusals: APP_NOT_FOUND, APP_MANAGER_REQUIRED, BAD_USER_INPUT, MODEL_GROUP_LIMIT_REACHED, SESSION_NOT_BOUND, APP_UNINSTALLED. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
appRef ID!
name String!
patterns [String!]!
instruction ActInstructionInput
deleteAppModelGroup Boolean! #2831 S1 - remove the App's model group of this name: an override reverts to the Team Agent's group, an App-only group is gone. The Agent's group itself is never deleted from here. Whoever manages the App only. Refusals: APP_NOT_FOUND, APP_MANAGER_REQUIRED, BAD_USER_INPUT, MODEL_GROUP_NOT_FOUND, SESSION_NOT_BOUND, APP_UNINSTALLED. #3323: the App-manager arm also admits the manager's held worker on an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12), recorded as one app.manager-act event, ids only.
appRef ID!
name String!
instruction ActInstructionInput
startImpersonation StartImpersonationResult! Start impersonating another member of orgRef (admin support/diagnostics). Caller must be a live ADMIN/OWNER of the org (platform ADMIN/OWNER is OWNER-equivalent), the target a live member, PEER-OR-BELOW (an org ADMIN may not impersonate an org OWNER), never self. Returns the audit session and a short-TTL token (returned exactly once) whose requests run READ-ONLY as the target. Org-scoped reads are restricted to this one org; personal/private memories and identity-based owner grants are excluded. Public-resource read gates remain applicable. Every mutation except stopImpersonation is rejected. Every request re-validates the session row, so stopping it (or demoting the admin) kills the token immediately.
orgRef String!
userRef String!
reason String
stopImpersonation ImpersonationSession! Stop an impersonation session (writes endedAt; the audit row is never deleted). With an impersonation token, id may be omitted (ends the token's own session — the one mutation an impersonated context may call). With a normal token, id is required and the caller must be the session's admin, an org ADMIN/OWNER of its org, or a platform admin. Idempotent on an already-ended session.
id ID
setDashboardWidgets [DashboardWidget!]! #772 — replace the caller's entire dashboard widget selection. Grid position is the array order; each widget's span (1-12) and rowSpan (1-4) are required and clamped server-side. Covers both create and update (the layout is always saved as a whole). Returns the new selection. Requires an authenticated user.
widgets [DashboardWidgetInput!]!
createDashboardWidgetPreset DashboardWidgetPreset! #806 — save a named widget configuration for the caller. 'name' is trimmed and must be 1-60 characters, unique among the caller's presets for that widget type; a duplicate is BAD_USER_INPUT. 'config' must be a JSON object within the same 4096 UTF-16 code-unit budget for serialized JSON as a placement's config. Requires an authenticated user.
type DashboardWidgetType!
name String!
config JSON!
updateDashboardWidgetPreset DashboardWidgetPreset! #806 — rename a preset and/or replace its settings. Partial: an omitted (or null) argument leaves that field alone; there is no way to clear 'config', since a preset with no settings has nothing to apply. 'type' is immutable — delete and re-create to move settings to another widget. A preset the caller does not own is indistinguishable from one that does not exist (NOT_FOUND).
presetRef ID!
name String
config JSON
deleteDashboardWidgetPreset Boolean! #806 — delete one of the caller's presets. Placements already seeded from it keep their config (apply copies; there is no live link). A preset the caller does not own is indistinguishable from one that does not exist (NOT_FOUND).
presetRef ID!
createNode Node! Create a single node. Rejects with NodeLocConflictError when a live node already exists at (memoryId, loc) — creating is create-only (spec 039 Phase 0 D1); a soft-deleted node at the target loc is resurrected. 'name' is required on creation, unlike updateNode. Target an explicit memoryId, or use install to create in an App's Agent install memory; supplying both targets is BAD_USER_INPUT. Include tags (#2040): content may carry {{> target settings}} tags. Writes that make a tag malformed refuse INVALID_INCLUDE; a tag the write adds or changes whose target is missing, deleted or not readable by the writer refuses INCLUDE_TARGET_UNAVAILABLE (one error for all three; tags already stored are not re-checked, #2041); and one that would make the node include itself INCLUDE_CYCLE; nothing is written. A chain deeper than 10 is not refused: it saves, and reads show the broken-include notice past level 10 (#2134). Each tag's target gets a derived edge (governed kind INCLUDE) that only the content owns: editing or deleting it directly refuses INCLUDE_EDGE_DERIVED.
input CreateNodeInput!
createSpecNode Node! #1201 — the CREATE door for the spec kind. A write that would produce a node with role: 'spec' or a dotted 'spec.*' sub-role must come through here; the generic createNode refuses it. PURE ROUTING: it validates nothing and knows nothing beyond which kind it is the door for. The authoring RULES stay in the tool that owns them ('hadron spec', 'hadron coding'), which is a closed-list exception on the audience ground. STRENGTH: DILIGENCE. This is the intended authoring door for spec tools (#1152); the server does not attest which client binary called it. A determined caller may omit the label, and a citation resolves without it. Specs are deliberately not treated as a security concern; the destructive half is closed by #1182/#1184, which made createNode mint-or-refuse and race-safe. Exempt from its OWN kind only — it is fully subject to every other kind and to Channel address protection, so it cannot forge a chat message. Deliberately NOT an MCP tool: an agent's node surface is hadron_create_node, which refuses, and that absence is the mechanism rather than an oversight.
input CreateNodeInput!
reserveSpecCitation Node! #1450 — reserve a citation as a placeholder, in any memory since #1591: an unminted spec node at loc (role spec, nodeType info) marked isPlaceholder, so links can point at it and the placeholders left are the corpus's to-do list. Writing real content through updateSpecNode turns it into a real spec at the same citation; minting refuses while a placeholder remains. Refuses NodeLocConflictError at a live loc. memoryRef accepts the memory's ID or URN.
memoryRef ID!
loc String!
name String
allocateSpecNode Node! #1178 — allocate the next citation under parentLoc and reserve it as a placeholder, in one transaction: mint-or-refuse, so a client never reads sibling numbers and writes the next. Numbers follow hadron spec new: features in tens (010..990), rules and flows by one (01..99), rule 00 never, after lands strictly above it. A number ever minted is never handed out again (R216) while a row or alias of it remains, and a loc held by a row of any state is skipped. Refuses SPEC_PARENT_NOT_FOUND, SPEC_PARENT_NOT_NUMBERED and SPEC_NUMBER_SPACE_EXHAUSTED; an unreadable memory is not found.
memoryRef ID!
parentLoc String!
after Int
name String
renumberSpec SpecRenumberResult! #1449 — renumber an UNMINTED spec (#1591: draft rights are per node): move it and its subtree from fromLoc to toLoc with no URN alias, refusing NODE_MINTED { locs } if any moved node is minted, then rewrite every node URN in the corpus that cites the moved specs, each as a normal edit. Bare text citations (labels, names) are reported in textCitations, not rewritten. dryRun returns the plan and writes nothing. The move is atomic; each rewrite is a separate guarded edit, and one that fails is reported FAILED without undoing the move.
memoryRef ID!
fromLoc String!
toLoc String!
dryRun Boolean
mintMemoryNodes SpecCorpusMintReport! #1591 — mint the live nodes of a memory in the mint scope, at once, excluding comment nodes and the decision role family. The scope is the unminted nodes plus (#1612) minted nodes whose content changed since their minted revision or that have no recorded minted revision; a re-mint keeps the first mint's time and minter. Each node is stamped with its current revision and that revision's approval hash (Node.mintStatus); a minted node's moves then record URN aliases. Refuses SPEC_CORPUS_MINT_BLOCKED while any blocker remains among the nodes in scope: a placeholder, an unresolved reference, a structural lint error over spec-marked or citation-shaped nodes (nodetype-info, tag-spec, serialization-leak, duplicate-loc), a stale abstract once staleAbstractsBlock is true, NOT_APPROVED (the current revision is not approved), TAMPERED (approved text changed outside the revision system), or CITES_UNMINTED (an edge into another memory's node that is not minted). Minted nodes outside the scope are not re-checked. dryRun returns the full report without minting. Any writer of the memory. memoryRef accepts the ID or URN. A real run holds every write to the memory off while it checks and stamps, and refuses SPEC_CORPUS_BUSY (retryable) if a write is already in flight. Encrypted memories are refused (SPEC_CORPUS_ENCRYPTED_UNSUPPORTED). Minting protects nothing by itself: minted-spec permanence (#1468) is switched off for now.
memoryRef ID!
dryRun Boolean
mintSpecCorpus SpecCorpusMintReport! #1448, generalized by #1591 — the same operation as mintMemoryNodes, kept under its original name.
memoryRef ID!
dryRun Boolean
updateSpecNode Node! #1201 — the UPDATE door for the spec kind, and the counterpart of createSpecNode. Same posture: pure routing, exempt from its own kind only, not an MCP tool. It is needed because the gate reads the RESULTING state: editing a node that already carries this kind still produces one, so the generic updateNode refuses it even when the edit touches neither signal. That is the point — a spec node must not be rewritable through the generic surface. Identical to updateNode otherwise, selectors included ('id' XOR 'memoryId' + 'loc'); it never creates and never moves.
input UpdateNodeInput!
createReviewNode Node! #1201 — the CREATE door for the review kind. A write that would produce a node with role: 'review' or a dotted 'review.*' sub-role must come through here; the generic createNode refuses it. PURE ROUTING: it validates nothing and knows nothing beyond which kind it is the door for. The authoring RULES stay in the tool that owns them ('hadron spec', 'hadron coding'), which is a closed-list exception on the audience ground. STRENGTH: SECURITY. A review is not coding-specific — any work performed can be reviewed, and a review may be a SAFETY CHECK. So an attacker can modify a work assignment AND remove the reviews meant to catch that. Omitting the label is self-defeating in its own way: an unlabelled check is invisible to the review tooling, so it is not a check. Exempt from its OWN kind only — it is fully subject to every other kind and to Channel address protection, so it cannot forge a chat message. This mutation is not itself an MCP tool; its MCP counterpart is the deliberate hadron_create_review tool, separate from hadron_create_node, which refuses (#1301 names it in the refusal).
input CreateNodeInput!
updateReviewNode Node! #1201 — the UPDATE door for the review kind, and the counterpart of createReviewNode. Same posture: pure routing, exempt from its own kind only; its MCP counterpart is hadron_update_review. It is needed because the gate reads the RESULTING state: editing a node that already carries this kind still produces one, so the generic updateNode refuses it even when the edit touches neither signal. That is the point — a review node must not be rewritable through the generic surface. Identical to updateNode otherwise, selectors included ('id' XOR 'memoryId' + 'loc'); it never creates and never moves.
input UpdateNodeInput!
createTaskNode Node! #1201 — the CREATE door for the task kind. A write that would produce a node with isRunnable: true must come through here; the generic createNode refuses it. PURE ROUTING: it validates nothing and knows nothing beyond which kind it is the door for. The authoring RULES stay in the tool that owns them ('hadron spec', 'hadron coding'), which is a closed-list exception on the audience ground. STRENGTH: CAPABILITY. The only one of the three whose gate cannot be evaded by omission, which is why it carries the security case. It keys on 'isRunnable' rather than on 'role': a label is caller-set and freely dropped, while omitting the capability means the node does not run. The threat is a memory shared with someone who authors a runnable node that reads the owner's data when the OWNER runs it (#1202). Exempt from its OWN kind only — it is fully subject to every other kind and to Channel address protection, so it cannot forge a chat message. This mutation is not itself an MCP tool; its MCP counterpart is the deliberate hadron_create_task tool, separate from hadron_create_node, which refuses (#1301 names it in the refusal).
input CreateNodeInput!
updateTaskNode Node! #1201 — the UPDATE door for the task kind, and the counterpart of createTaskNode. Same posture: pure routing, exempt from its own kind only; its MCP counterpart is hadron_update_task. It is needed because the gate reads the RESULTING state: editing a node that already carries this kind still produces one, so the generic updateNode refuses it even when the edit touches neither signal. That is the point — a task node must not be rewritable through the generic surface. Identical to updateNode otherwise, selectors included ('id' XOR 'memoryId' + 'loc'); it never creates and never moves.
input UpdateNodeInput!
updateNode Node! Update an existing node. Identify it by 'id' (PK or fully-qualified node URN) XOR the ('memoryId', 'loc') combo, or by ('install', 'loc') for an App's Agent install memory. Supplying install together with id or memoryId is BAD_USER_INPUT; the ordinary selectors remain mutually exclusive and one selector is required. Rejects with NODE_NOT_FOUND when the target does not exist; updateNode never creates and never moves (relocation is moveNode's job, D3). Every content field is optional — omitted fields are preserved ('name' included, D4; 'abstract' keeps its omit/null/string contract; omitted 'tags' are preserved, issue #235). Include tags (#2040): content may carry {{> target settings}} tags. Writes that make a tag malformed refuse INVALID_INCLUDE; a tag the write adds or changes whose target is missing, deleted or not readable by the writer refuses INCLUDE_TARGET_UNAVAILABLE (one error for all three; tags already stored are not re-checked, #2041); and one that would make the node include itself INCLUDE_CYCLE; nothing is written. A chain deeper than 10 is not refused: it saves, and reads show the broken-include notice past level 10 (#2134). Each tag's target gets a derived edge (governed kind INCLUDE) that only the content owns: editing or deleting it directly refuses INCLUDE_EDGE_DERIVED.
input UpdateNodeInput!
updateNodeData Node! Shallow-merge a JSON patch into a node's 'data' bag. The supplied JSON's top-level keys are written over the node's existing 'data' (the patch wins on key collision); keys the patch doesn't mention are preserved. If the node has no 'data' yet, the supplied JSON becomes its 'data' verbatim. 'data' must be a JSON object (not an array or scalar). 'nodeRef' is a node ID or fully-qualified URN. Honors the same single-write invariants as updateNode (per-memory write auth, encryption, revision history, git mirror). Returns the updated node.
nodeRef ID!
data JSON!
reason String
authoredWith AuthoredWithInput
updateNodeProperties Node! #742 - Shallow-merge a JSON patch into a node's structured 'properties' (the schema-governed JSONB column, DISTINCT from 'data'). The patch's top-level keys are written over the node's existing 'properties' (patch wins on collision); unmentioned keys are preserved; a node with no 'properties' takes the patch verbatim. ONE EXCEPTION (#1227): an OBJECT under 'exports' - the per-host skill export declarations, keyed by host (D12) - is applied as a JSON Merge Patch (RFC 7396), not replaced. Hosts and their fields merge recursively, a null member DELETES that host or field, and scalars/arrays replace. So '{exports: {codexSkill: {enable: false}}}' flips one flag and keeps the host's name, description and every other host, and '{exports: {codexSkill: null}}' removes that host. A non-object 'exports' in the patch (null, a scalar, an array) keeps the top-level rule and replaces the stored value. The merge runs under a per-node lock, so two callers writing different hosts at once both land - do NOT read-modify-write 'exports' client-side, which can lose a concurrent writer's host. 'properties' must be a JSON object (not an array or scalar). 'nodeRef' is a node ID or fully-qualified URN. On a schema-governed memory the MERGED result is validated against the memory's schema (BAD_USER_INPUT on a violation). 'properties' is plaintext at rest (never encrypted), so the merge + conformance check need no key — but the write still honors the same single-write invariants as updateNode (per-memory write auth, an active session on an encrypted memory, revision history, git mirror). Returns the updated node.
nodeRef ID!
properties JSON!
reason String
authoredWith AuthoredWithInput
createObject JSON! #745 — Object store: the legible sugar surface over structured storage. An object IS a node; these ops are thin projections onto createNode / updateNodeProperties / deleteNode, inheriting all their invariants (auth, encryption, schema conformance, revisions, atomic merge). Create an object in a collection. 'memoryRef' is a memory ID or fully-qualified URN (relative refs are rejected, spec 022). 'type' is the collection (node objectType); 'fields' are the flat, typed properties (validated against the memory schema when the collection is declared). The node's loc is auto-derived (<type>:<key ?? generated-id>) and hidden; pass 'key' for a human-meaningful id (a single segment, no ':'), 'name' to override the derived node name. Reserved object field names: id, type; these cannot be supplied in fields. Returns the flat object.
memoryRef String!
type String!
fields JSON!
key String
name String
updateObject JSON! Merge fields into an existing object (server-side atomic shallow merge + schema conformance on the result). 'ref' is the object id (or node URN); 'fields' wins on key collision, unmentioned keys preserved. Returns the updated flat object. The merge is shallow for EVERY field, including one named 'exports': the per-host merge-patch updateNodeProperties applies to 'properties.exports' (#1227) is a node-level skill-declaration rule and does not apply to object fields.
ref ID!
fields JSON!
reason String
deleteObject Boolean! Delete an object (soft by default; 'hard: true' removes the row). 'ref' is the object id (or node URN). Returns true on success.
ref ID!
hard Boolean
searchReplaceInNodes SearchReplaceResult! Bulk search-and-replace text across selected nodes (literal or regex). Honors per-memory write auth, encryption, revision history, abstract staleness, and re-embedding. Supports dryRun preview.
input SearchReplaceInNodesInput!
searchReplaceInSpecNodes SearchReplaceResult! Governed bulk replacement inside one spec corpus, with exact preview binding. Every target must be unminted (#1591); SEARCH_REPLACE_NOT_DRAFT names minted ones.
input SpecSearchReplaceInput!
deleteNode Boolean! Delete a node identified by 'nodeRef' (a node ID or fully-qualified URN; #542). Soft-delete by default (sets deletedAt; the node disappears from reads, matching the hadron_delete_node MCP tool). Pass hard: true to remove the row entirely (cascades edges + NodeRevision via FK) — irreversible. #391. A re-delete of an already soft-deleted node is idempotent (the ref resolves through the tombstone). If the node has descendants (nodes under its loc prefix), a plain delete REFUSES with NODE_HAS_DESCENDANTS (carrying the count) rather than silently orphaning the subtree — parity with the hadron_delete_node MCP tool. Pass recursive: true to delete the node's whole loc-subtree — the node at its loc PLUS every descendant, matched on ':' path boundaries (so deleting 'auth' does not touch 'authoring'). The subtree lives in one memory, so the single write-access check covers it; 'hard' applies to the whole subtree. A hard delete cascades edges on both endpoints via FK. If any affected node is on an edge that bridges this memory to another, the hard delete REFUSES with CROSS_MEMORY_EDGES (the caller may not own the other memory) unless cascadeCrossMemoryEdges: true. A non-recursive soft re-delete of an already soft-deleted node is an idempotent no-op that preserves its audit stamp.
nodeRef ID!
hard Boolean
recursive Boolean
cascadeCrossMemoryEdges Boolean
restoreNodeRevision Node! Restore a node to a previous revision (#617). Default (truncate: false): snapshots the CURRENT node state into history first, then restores the node's fields to the revision — non-destructive, the restore itself becomes undoable. truncate: true: restores the node's fields to the revision AND deletes every NodeRevision NEWER than the selected one (createdAt strictly greater), WITHOUT creating a pre-restore snapshot. Boundary is EXCLUSIVE of the selected row: the selected revision is KEPT and becomes the new baseline (the most-recent snapshot afterward); its era and older survive. The live revision counter still advances monotonically for the restore itself. Restore + truncate run in one transaction (atomic).
revisionId ID!
truncate Boolean
deleteNodeRevision Boolean! Delete a single node-revision snapshot by id (#617). Auth: the node's memory write access (as restoreNodeRevision). Throws NOT_FOUND for an unknown id.
revisionId ID!
updateNodeRevision NodeRevision! Set or clear the user-facing label on a revision snapshot (#620, NodeRevision.revLabel, 500-char cap). Omit revLabel to preserve; pass null to clear. Auth: the node's memory write access (as deleteNodeRevision) PLUS the nodeRevision query's read gates — it returns the full snapshot, so a soft-deleted node or a snapshot captured in an unreadable memory answers the same NOT_FOUND as an unknown id.
revisionId ID!
revLabel String
approveNode NodeApprovalReceipt! #1591 — approve the node's CURRENT revision: record who, when, and the approval hash of its title/abstract/content. Pass revision to approve only if it is still the one you read (REVISION_MISMATCH otherwise). A memory writer may approve ordinary nodes, the author included; placed boot prompts also require their dedicated manager-as-self gate. Comments and decision-family nodes are refused. Idempotent: an approved revision keeps its existing approval. Refuses NODE_IS_PLACEHOLDER, and ENCRYPTED_MEMORY_NOT_APPLICABLE on any encrypted memory, even with a cached session key.
nodeRef ID!
revision Int
recordNodeContentValidationReport NodeContentValidationReportReceipt! #1332 (hrn:node:hadronmemory.com:specs:cor:dmo:160:01) — record the result of running the node's validation task on revision nodeRevision of the node. Advisory: it never edits the node or blocks a write, and a report for an older revision is stored as history without changing the current revision's state. validationTaskRef is the task the node's role rule names NOW (its id or node URN; read it from NodeRoleRule.validationTask) and validationTaskRevision the task revision that ran. Any writer of the node's memory may record one except the author of nodeRevision, decided from its authorship stamp: for HUMAN, that person acting as themselves through any credential is refused (a worker they hold may report); for TASK, a headless run whose entry task is the author task is refused (another run is CHECKED; any other caller is AUTHOR_UNKNOWN); with no stamp every writer is AUTHOR_UNKNOWN. The reporter is derived by the server (a run, a worker session, a person by user id, or an App key), never from the request. runId (1-200 characters) makes a retry idempotent: within this node in this memory, the same runId from the same reporter for the same nodeRevision and task revision returns the first report (replayed: true); any other use of it is CONTENT_VALIDATION_RUN_ID_CONFLICT, which carries nothing from the stored report. Refusals, in order, each writing nothing: NODE_NOT_FOUND (unreadable or missing memory, missing node); FORBIDDEN (not a writer); SESSION_NOT_BOUND (the request named a session that is not one of the caller's open sessions); CONTENT_VALIDATION_REPORTER_UNKNOWN; CONTENT_VALIDATION_NODE_REVISION_INVALID (newer than the current revision); CONTENT_VALIDATION_NOT_CONFIGURED (no validation task for the node's role); CONTENT_VALIDATION_WRONG_TASK for EVERY report from a caller who cannot read a validation task the rule names, whatever task and revision it names and whether or not that task is broken, so the later checks never run for that caller (a reference that no longer resolves, the task or its memory deleted, is TASK_BROKEN for every caller); CONTENT_VALIDATION_TASK_BROKEN; CONTENT_VALIDATION_WRONG_TASK (a task other than the one the node's rule names); CONTENT_VALIDATION_TASK_REVISION_INVALID (newer than the task's current revision); CONTENT_VALIDATION_REPORTER_IS_AUTHOR; CONTENT_VALIDATION_RUN_ID_CONFLICT. BAD_USER_INPUT for a malformed argument, and a retryable CONFLICT if the node changed during the call.
nodeRef ID!
nodeRevision Int!
validationTaskRef ID!
validationTaskRevision Int!
outcome NodeContentValidationOutcome!
runId String
requestNodeSignature SigningRequest! #1632 (hrn:node:hadronmemory.com:specs:cor:dmo:130:03) — ask for a node's current content to be signed. Any reader of the node may ask, agents included; agents never sign. expectedRevision, when given, must still be current (REVISION_MISMATCH). signerRef names one signer (a user id); omitted, any writer of the memory may sign. Refusals: NODE_NOT_FOUND, ENCRYPTED_MEMORY_NOT_APPLICABLE, and (hrn:node:hadronmemory.com:specs:cor:dmo:130:02, Holger #10430) COMMENT_NOT_SIGNABLE, NODE_IS_PLACEHOLDER, REVISION_MISMATCH, SIGNER_NOT_FOUND, and (Holger #11094, #1904) SIGNER_NOT_A_WRITER when the named signer may not write the node's memory (checked again when they sign or decline). No call takes an assertion: the signer signs on the server-hosted ceremony page (S2b-2).
nodeRef ID!
expectedRevision Int
signerRef ID
withdrawSigningRequest SigningRequest! #1632 — withdraw an open signing request. Only the requester account, from any of its sessions (#10397). Refusals (hrn:node:hadronmemory.com:specs:cor:dmo:130:03, Holger #10430): SIGNING_REQUEST_NOT_FOUND, SIGNING_REQUEST_NOT_REQUESTER, SIGNING_REQUEST_ENDED (extensions.state).
id ID!
requestGrantSignature GrantSigningRequest! #3649 slice B (hrn:node:hadronmemory.com:specs:cor:acl:140:07) — ask for one pending grant to be signed. Two callers may ask: a bound worker session in its own App, or a person acting as themselves who manages the grant's live, installed App (as appGrants reads it); workers never sign. No signer is named: whoever signs must be able to issue it. The request pins the grant's version and terms hash. Refusals: FORBIDDEN while impersonating; GRANT_NOT_FOUND (unknown and unreadable alike); GRANT_NOT_PENDING (activated, revoked, or its holder gone; no state is named); GRANT_EXPIRED (past its expiry, so it can never be signed); GRANT_TERMS_UNREPRESENTABLE (extensions.reason). No call takes an assertion: the signer signs on the server-hosted ceremony page.
grantRef ID!
createGrant Grant! #3690 PR 2 (hrn:node:hadronmemory.com:specs:cor:acl:140:05) — ask for a grant. A bound worker session may call it, in its own App, for itself or its role agent (installed in the App). #3711: a PERSON who manages the App may call it too, naming the App in input.appRef, for a worker of the App or an agent installed in it; the row records that person, never a worker. Either way the row is born pending and allows nothing until it is signed (#3649). Returns the grant as grant(ref:) reads it (a manager reads it as appGrants does). Refusals, each before any write and none naming a submitted value: GRANT_REQUESTER_NOT_WORKER, GRANT_NOT_MANAGER (a person arm caller who does not manage the App, and an unknown App: the same answer), GRANT_HOLDER_NOT_ALLOWED (any other holder, or an agent not installed here), GRANT_ACTION_UNKNOWN, GRANT_VALUES_INVALID (a value that does not match the action's declared parameters, or an undeclared key, or a list above 100 entries per parameter, or a node-typed value that does not name a node the requester can read: a missing, deleted, unreadable and malformed id are the same answer, hrn:node:hadronmemory.com:specs:cor:acl:140:07), GRANT_TERMS_INVALID (including a reason above 2,000 Unicode code points; hrn:node:hadronmemory.com:specs:cor:acl:140:01). These write-path limits never prevent rebuilding an existing grant's signature terms. Over MCP only the person arm exists (hadron_create_grant, ruling 0255 item 21). Present only where signing is switched on (PASSKEY_SIGNING_ENABLED).
input CreateGrantInput!
revokeGrant Grant! #3711 (hrn:node:hadronmemory.com:specs:cor:acl:140:05, :03) — revoke a grant now, unsigned, in any state but ended. By the issuer (while still a member of the App's Org), by whoever manages the App, or by a held worker on a validated instruction from a holder who may. Returns the grant as appGrants reads it. The first end stands: a grant already revoked, withdrawn or whose holder departed is returned as it is, with no second stamp and no second REVOKE event. Judged on the locked current row. Refusals: GRANT_NOT_MANAGER (not allowed, and a grant that does not exist or cannot be seen: the same answer).
ref ID!
instruction ActInstructionInput
withdrawGrant Grant! #3711 (hrn:node:hadronmemory.com:specs:cor:acl:140:05, V57) — withdraw a grant the caller asked for, while it is still pending. Only the recorded requester: a person, or the worker session that asked. It is the grant's one end (revoked_at, with the person as revoker) and one REVOKE event; no new state is named. A withdrawal that loses the race to the signature is refused. Refusals: GRANT_NOT_FOUND (unknown and unreadable alike), GRANT_NOT_REQUESTER, GRANT_NOT_PENDING (activated). A grant already ended is returned as it is.
ref ID!
withdrawGrantSigningRequest GrantSigningRequest! #3649 slice B (hrn:node:hadronmemory.com:specs:cor:acl:140:07) — withdraw an open grant signing request. Only the requester account, from any of its sessions or workers, among the two callers who may read the grant (a bound worker in its own App, or a person who manages the App); a manager who did not ask is refused SIGNING_REQUEST_NOT_REQUESTER. Refusals: FORBIDDEN while impersonating, SIGNING_REQUEST_NOT_FOUND, SIGNING_REQUEST_NOT_REQUESTER, SIGNING_REQUEST_ENDED (extensions.state).
id ID!
approveMemoryNodes ApproveMemoryNodesResult! #1591 — approve the current revision of every live node of a memory (ID or fully-qualified URN) in the mint scope (unminted, or minted and changed since or with no recorded minted revision, #1612) that isn't approved yet, in one transaction. Placeholders are skipped and reported.
memoryRef String!
createComment Comment! #1606 — start a thread on a node (hrn:node:hadronmemory.com:specs:cor:dmo:110). Needs write access to the target's memory. Commentable classes: app, knowledge, personal, group, system; private memories are not commentable. anchorRevision defaults to the target's current revision; an older one anchors there while its text is still retained. The anchor hash is computed by the server. Typed refusals: COMMENT_TARGET_NOT_FOUND, COMMENT_FORBIDDEN, COMMENT_TARGET_IS_COMMENT, COMMENT_MEMORY_NOT_COMMENTABLE, COMMENT_OPEN_THREAD_EXISTS, COMMENT_ANCHOR_REVISION_INVALID, COMMENT_ANCHOR_REVISION_UNAVAILABLE, COMMENT_BODY_INVALID, COMMENT_IMPERSONATION_REFUSED.
targetRef ID!
body String!
quote String
anchorRevision Int
replyToComment Comment! #1606 — reply in a thread; commentRef may be any comment of it. Allowed on a resolved thread, which stays resolved (Holger, DAB).
commentRef ID!
body String!
editComment Comment! #1606 — the author edits a comment's body and/or quote. COMMENT_NOT_AUTHOR otherwise.
commentRef ID!
body String
quote String
expectedRevision Int!
deleteComment Comment! #1721 — delete one comment: its author (with write access), or anyone who may delete others' comments (the memory's manager, or a platform admin outside personal and private memories). A top-level comment with live replies stays as a deleted stub with no text; any other comment is soft-deleted and gone from every read, and a stub goes with its last live reply (hrn:node:hadronmemory.com:specs:cor:dmo:110:05). Returns the comment as deleted. COMMENT_NOT_AUTHOR for a writer who is not the author; COMMENT_DELETED for a stub.
commentRef ID!
expectedRevision Int!
resolveCommentThread Comment! #1606 — resolve a thread: its author or any writer of the memory. commentRef is the top-level comment; returns it.
commentRef ID!
expectedRevision Int!
reopenCommentThread Comment! #1606 — reopen a resolved thread: its author or any writer of the memory.
commentRef ID!
expectedRevision Int!
deleteCommentThread Boolean! #1606 — a memory admin deletes a whole thread (soft: gone from every read, limit and check; the rows stay for audit, with no revision history, #1721). commentRef may be any comment of it.
commentRef ID!
reason String!
createDecisionLog DecisionLog! #1641 — create a decision log at loc in a memory: needs management rights on the memory, or the owner role in its live, installed App for non-personal/non-private memories. Impersonation is refused. Refused in an encrypted memory (DECISION_LOG_ENCRYPTED), a git-mirrored one (DECISION_LOG_MIRRORED), a system memory (DECISION_LOG_SYSTEM_MEMORY), an anonymous one (DECISION_LOG_ANONYMOUS_MEMORY), at a loc occupied by a live or deleted node at or beneath it (DECISION_LOG_EXISTS), or inside a decision's subtree. Deciders are user ids, each able to write the memory (DECISION_DECIDER_NOT_ELIGIBLE; hrn:node:hadronmemory.com:specs:cor:dmo:130:09).
memoryRef ID!
loc String!
name String
prefix String
defaultDeciders [ID!]!
eligibleDeciders [ID!]
setDecisionLogDeciders DecisionLog! #1641 — replace a log's default (and, when given, other eligible) deciders, as an audited revision of the log. Existing decisions keep theirs. Needs management rights on the memory, or the owner role in its App.
logRef ID!
defaultDeciders [ID!]!
eligibleDeciders [ID!]
expectedRevision Int!
reason String!
askDecision Decision! #1641 — ask a decision in a log: the server issues the next code using the log prefix (DA, DB, … with default D) and renders the content. Any writer of the log's memory, agents included, outside impersonation. Refusals: DECISION_INVALID (with JSON pointers), DECISION_RECOMMENDATION_MISSING, DECISION_TIER_TOO_LOW, DECISION_DECIDER_NOT_ELIGIBLE.
logRef ID!
input AskDecisionInput!
amendDecision Decision! #1641 — amend a writable decision. Memory write access is always required; before any answer, any writer; after one, a decider only. Urgency is a decider's to change; lowering the tier is a decider's, before an answer, never when it authorizes. Refusals: NODE_WRITE_CONFLICT, DECISION_PART_RENUMBER, DECISION_ANSWER_IMMUTABLE, DECISION_NOT_DECIDER.
ref ID!
input AmendDecisionInput!
expectedRevision Int!
reason String!
withdrawDecision Decision! #1641 — withdraw a decision (terminal; the code stays consumed): the asker or a decider, a decider once answered. DECIDED ones are superseded instead (DECISION_ANSWERED_DECIDED).
ref ID!
reason String!
expectedRevision Int!
purgeUnansweredDecision Boolean! #1641 — a platform admin hard-deletes a decision that was never answered, recorded on its log (DECISION_ANSWERED otherwise). The code stays consumed.
ref ID!
reason String!
clearNodeHistory Int! Delete ALL NodeRevision rows for a node, returning the count deleted (#617). 'nodeRef' is the node's PK or fully-qualified URN. Auth: the node's memory write access. An unknown ref throws NODE_NOT_FOUND. Reachable on a soft-deleted node (purging residual history is a cleanup op).
nodeRef ID!
moveNode Node! Relocate a node (#564). 'sourceRef' is the node's PK or fully-qualified URN. The destination is EITHER 'targetUrn' (the node's new full URN — new memory and/or loc) OR 'targetMemoryRef' (a memory ID/URN; the node keeps its current loc, only its memory changes) — supply exactly one. The node keeps its id, so all incoming/outgoing edge references stay valid. Fails loudly with NODE_ALREADY_EXISTS if a live node already occupies the destination. Requires write access to both the source and destination memories. On a cross-memory move, select Node.moveLinkWarnings to see raw relative content links that now miss or resolve to another node.
sourceRef ID!
targetUrn String
targetMemoryRef ID
planNodeMove NodeMovePlan! Plan with the real move's gates and raised refusals, without locks, reconciliation, writes or mirror effects. Nodes in loc order; limit clamps to 1–1000 (default 100), with total and truncation disclosed. No edges. A point-in-time answer, not a reservation. This plan-only call is on the mutation root by rulings 0210/0211, so impersonation sessions are refused even though planning writes nothing. hrn:node:hadronmemory.com:specs:cor:api:190:03.
sourceRef ID!
targetUrn String
targetMemoryRef ID
limit Int
cloneNode Node! Clone a node to a new location, returning the NEW node with a fresh id (#564). Same selector shape as moveNode ('sourceRef' + exactly one of 'targetUrn' / 'targetMemoryRef'). Copies the source's own fields; outgoing edges are copied only where they naturally resolve — a live node exists at the target's loc in the destination memory. Incoming edges are not copied. Fails loudly if the destination loc is already occupied. Requires read access to the source memory and write access to the destination.
sourceRef ID!
targetUrn String
targetMemoryRef ID
mergeNodes Node! Fold one node (source) into another (target), returning the updated target. Per-field strategy: text fields (CONTENT/ABSTRACT/DESCRIPTION) concatenate target-first; TAGS unions; DATA/PROPERTIES shallow-merge with the target winning on key collisions; EDGES re-points the source's relationships onto the target. 'include' selects which fields fold in (omitted = all). 'deleteSource: true' hard-deletes the source afterward. Honors per-memory write auth, encryption, revision history, abstract staleness, and re-embedding (same invariants as createNode/updateNode).
input MergeNodesInput!
mergeMemories Memory! Merge one memory (source) into another (target), returning the updated target. Source nodes whose loc already exists in the target are folded into their counterpart via the mergeNodes field strategy ('include' selects which fields); source nodes with no counterpart move over with their loc unchanged. Edges follow. The source memory ends up empty; 'deleteSourceMem: true' then deletes it. v1 rejects encrypted source or target memories and system/app classes. An address the merge would move a node or a carried comment into, but which the target holds with a SOFT-DELETED node, refuses MERGE_TARGET_LOC_TOMBSTONED (the tombstone still owns the address; up to 25 locs named, with the full count). A tombstone present when the merge starts refuses before any batch commits; one that appears mid-merge refuses the batch it hits, and batches already committed stay committed (re-running completes the merge). Hard-delete the tombstone, or recreate a node there so it folds, then re-run. The merge commits in batches, and is resumable. A refusal raised after some batches committed (#1686) says so: it carries extensions.partialMerge { applied, relocated, folded, edgesMoved, edgesDropped, remainingSourceNodes, sourceIntact, remedy } and keeps its own code, or is MERGE_PARTIALLY_APPLIED (with causeCode) when the cause was untyped. The source memory is never deleted by a refused merge; resolve the blocker and re-run the same merge to finish it. A failure after the merge completed (re-indexing or reading back the target) carries partialMerge too, with remainingSourceNodes 0 and sourceIntact false when deleteSourceMem had removed the source. A refusal with no partialMerge applied nothing.
input MergeMemoriesInput!
replaceSubtree ⚠️ Int! Retired. After the ordinary concealed-memory and write-access checks, calls return REPLACE_SUBTREE_RETIRED without changing nodes or edges. The field remains temporarily so existing clients get a clear refusal rather than an unknown-field error.

⚠️ DEPRECATED

Retired (#454): every authorized call refuses with REPLACE_SUBTREE_RETIRED and writes nothing. Use the canonical node write mutations.
ownerRepo String!
memoryId String!
nodes [NodeInput!]!
edges [EdgeInput!]!
createEdge Edge!
sourceRef ID!
targetRef ID!
name String
loc String
description String
isRunnable Boolean
condition JSON
priority Int
data JSON
updateEdge Edge!
edgeRef ID!
name String
loc String
description String
isRunnable Boolean
condition JSON
priority Int
data JSON
deleteEdge Boolean!
edgeRef ID!
runTask String! Render or execute a node identified by a single nodeRef (a node PK or a fully-qualified node URN, hrn:node:<root>:<memory>:<loc>). This explicit-reference operation does not require isRunnable=true. The runnable flag governs by-name task discovery, resolution and listing (hrn:node:hadronmemory.com:specs:cor:api:060:01). The reference is resolved by the shared resolveNodeRef (#542). A bare loc without a memory is rejected — pass a full URN or an ID. For loose-name matching and interactive task selection use the MCP hadron_run_task tool, which resolves to a concrete nodeRef before calling this. By default RENDERS the task: returns the assembled instructions (node content with {{arg}} substitution and referenced nodes) for an LLM agent to execute. Pass appRef (App PK or URN) to EXECUTE instead (#529): the server mints a MANUAL app run for the resolved task under that App and returns the run id (poll appRun(ref:) for status + output). runAsSelf attributes the run to the caller. Without appRef, behavior is unchanged. Spec cor:api:060.
nodeRef String!
args JSON
appRef ID
runAsSelf Boolean
agentRef ID
importNode ImportNodeResult! Import external content into a node (#457, sync v1). Source: exactly one of 'url' (server-fetched inline, SSRF-guarded, Readability-extracted, ~30s budget — the fetch carries NO user credentials, so authenticated pages must come as 'content') or 'content' (client-captured, e.g. the Web Clipper's authenticated DOM). Target: 'nodeUrn' XOR ('memoryId' + 'loc'); an existing node is updated IN PLACE (NodeRevision snapshot is the undo), a missing one is created. HTML converts to Markdown at the write seam (contentType defaults to text/html here, unlike createNode).
input ImportNodeInput!
createAgentSchedule AgentSchedule!
input CreateAgentScheduleInput!
updateAgentSchedule AgentSchedule!
id ID!
input UpdateAgentScheduleInput!
deleteAgentSchedule Boolean!
id ID!
triggerAppRun AppRun! Run an entry node now (MANUAL trigger) — same launch gate + kernel as a schedule.
input TriggerAppRunInput!
cancelAppRun AppRun! The kill switch manual handle: PENDING/RUNNING to CANCELLED (cor:agt:010:02).
id ID!
createAgentWebhook AgentWebhookCredentials! Create a webhook trigger — returns the URL path + platform token ONCE (D-2026-05-02).
input CreateAgentWebhookInput!
rotateAgentWebhook AgentWebhookCredentials! New secret + token; the old URL dies immediately.
id ID!
deleteAgentWebhook Boolean!
id ID!
createConnectionGrant ConnectionGrant! Grant an App install scoped access to a connection you OWN, using your own user credential with no App context (no App-key or on-behalf-of-run path). scopes must be a non-empty subset of {mail.read, mail.send, calendar.freebusy, calendar.read, drive.read}; duplicates are collapsed. expiresAt is optional; when supplied it must be a future ISO-8601 timestamp with an explicit timezone. appRef is a PK or App URN. A missing or unreadable connection answers NOT_FOUND.
connectionRef String!
appRef String!
scopes [String!]!
expiresAt String
revokeConnectionGrant Boolean! Revoke a connection grant you created (soft delete). Owner-only.
ref ID!
createPrincipalGrant PrincipalGrant! Grant a member extra management actions (org-ADMIN, interactive-only; design:grant-model). The grantee must be a live member of the org.
orgRef String!
userRef String!
actions [String!]!
expiresAt String
revokePrincipalGrant Boolean! Revoke an action grant (org-ADMIN, interactive-only; soft delete).
ref ID!
mintActionTickets Int! Mint comm.outbound tickets into the org ledger (org-ADMIN; cor:acl:050:04).
input MintActionTicketsInput!
setQuotaLimit QuotaCounter! Set the stored (enforced) quota limit for a scope x action (#510) - the operator dial that previously required psql. Org-ADMIN.
input SetQuotaLimitInput!
setAiModelPrice AiModelPrice! Append an effective-dated provider rate row (spec 046). PLATFORM ADMIN - org admins must never set the prices they are billed at.
input SetAiModelPriceInput!
grantCredits CreditLedgerEntry! Mint credits for an org - a positive grant ledger row (spec 046). PLATFORM ADMIN ONLY (self-grant risk); processor top-ups land here later.
input GrantCreditsInput!
updateMyPolicy User! Author YOUR user-layer action-policy link (cor:acl:040:02, #510). Null clears (= no restriction).
policy JSON
beginAssetUpload BeginAssetUploadResult!
input BeginAssetUploadInput!
completeAssetUpload Asset!
input CompleteAssetUploadInput!
setAgentAssetUploadEnabled App!
input SetAgentAssetUploadEnabledInput!
setAssetPublicLink Asset! #1667 — switch an asset's anonymous public link on or off. Only whoever manages the asset's memory; a refused request changes nothing. Returns the asset. On an App memory, a worker session acts only on a validated instruction, judged on its holder (hrn:node:hadronmemory.com:specs:cor:dmo:050:12): the holder must manage the App, exactly as for the holder as a person. Without an instruction a worker session is refused. An admitted instructed call that changes the flag writes one team event, ids only (no asset id). Other memory classes keep their own rules and ignore instruction.
assetRef ID!
enabled Boolean!
instruction ActInstructionInput
softDeleteAsset Asset!
assetId ID!
restoreAsset Asset!
assetId ID!
beginAssetUploadV2 BeginAssetUploadResult! Asset upload — v2 (spec 006-asset-upload-redesign) Memory-addressed begin: the caller specifies the destination memory directly, no agent traversal. Replaces agent-addressed beginAssetUpload during the deprecation window.
input BeginAssetUploadV2Input!
createAssetReferenceNode Node!
input CreateAssetReferenceNodeInput!
startSession Session! Open a session — and, when `input.workerRef` is given, a WORKER SESSION: the binding that makes the work attributable to that named teammate. The binding is held server-side and is independent of the caller's CHAT SESSION (the human's Desktop window, Claude Code session or IDE chat). **Ending your chat session does not end a worker session** (#1034): a chat session that closes leaves this session open until endSession — #1114 removed inactivity as a reason to end one, so nothing else will. The worker stops reading as LIVE once its idle window passes without a drive, which lets another bind proceed without ending the stale session or losing its unwritten handoff. A human HOLD stays in force until explicit release, so only its holder can bind it again. A client that ties its lifetime to a conversation must call endSession itself; nothing about closing a window reaches this server.
input SessionInput!
updateSession Session! #931: update a live session's mutable provenance fields (a PR is usually opened after startSession already ran). Explicit null clears; omitted preserves; an empty update is a valid liveness touch (bumps updatedAt, which liveness counts — #1114). id-only - sessions have no URN. Gate: platform admin, the session's App, or the attributed user (not via impersonation). An App key updates only user-less sessions (never one a person is behind), never a host-launched one, and a key ever granted host:operate updates none (#1934, hrn:node:hadronmemory.com:specs:cor:agt:070:04). Updates on an ended session stay allowed (late PR-merge attribution). #1931 — llmModel refreshes the model-family derivation; an explicit family wins. Null or omitted family metadata preserves the existing family. Unclassified models do not clear it. #4291 — effort reports the effort the session now runs at; null or omitted leaves it as last recorded. A report (model, family or effort) on a worker's OPEN session is also written to that worker's last-used record (Worker.lastUsed, hrn:node:hadronmemory.com:specs:cor:agt:060:04); a report on an ended session moves no record.
id ID!
prNumber Int
branch String
llmModel String
family String
effort EffortLevel
recordSessionOutcome Session! #2896 — report a session's outcome: outcome is a number from 0 to 1, outcomeRef an opaque reference of the reporter's (a ticket, a survey id) and outcomeMeta any JSON it wants kept. The same implementation as POST /sessions/:id/outcome, which stays for edge devices and webhooks. An outcome is a WRITE to the session, so it takes the session write gate: the attributed user, or a pure App key for its own App's user-less session (hrn:node:hadronmemory.com:specs:cor:dmo:070:05); the strict owner of a personal or private memory's session wins over a platform admin (hrn:node:hadronmemory.com:specs:cor:acl:010:02). Reporting is not driving: a lapsed session stays lapsed. A number outside 0..1 is BAD_USER_INPUT; an unknown or deleted session is BAD_USER_INPUT; a refused write is FORBIDDEN, and an OAuth credential limited to the MCP surface is FORBIDDEN with its reason.
sessionId ID!
outcome Float!
outcomeRef String
outcomeMeta JSON
endSession Session! End a session, and — for a worker-bound one — write its closing handoff (#1029). Ending a client's chat session does not end its worker session or call this operation. Inactivity alone never ends a session; the reaper enforces a hard expiresAt promised at session start. Other explicit platform lifecycle operations can also end sessions. It ends the SESSION, not any HOLD. Where a person bound the worker the name stays theirs until explicitly released (#1050, [`cor:agt:020:09`](hrn:node:hadronmemory.com:specs:cor:agt:020:09)), so only that holder can bind it again. A pure App-key **bind takes no hold** — which is a fact about the bind, not a promise about the worker's state when this returns: an eligible user may have forced a binding meanwhile and taken the name, and ending the App-key session leaves that hold and that session untouched. Gate (#931): platform admin, the session's App, or the attributed user (not via impersonation). An App key ends only user-less sessions (never one a person is behind), never a host-launched one, and a key ever granted host:operate ends none (#1934, hrn:node:hadronmemory.com:specs:cor:agt:070:04); a host ends a launched session only by reporting its worker.end. `handoff` is agent-composed prose: what landed, what is open, what is blocked, what the next driver should not repeat. The server owns where it goes (the worker's working memory, under the `handoffs` parent, at a lexically-ordered loc), so no client re-derives the convention. `summary` is NOT a smaller `handoff` (#1100). It sets `Session.summary`, a label on the session row — readable back through `session` / `sessions`, but read by no worker-continuity path, so the next driver never sees it. The two sit side by side and only one of them reaches that driver, so a caller writing a closing note picks by name: it is `handoff`. The two mistakes are not symmetric, and that is the whole hazard. Putting continuity prose in `summary` succeeds, returns a normal receipt, and produces NO handoff — discovered only once the context that could have written one is gone, and not correctable in place, since the sequence is append-only and adding a handoff to an ended session is refused. A repeat end without a new handoff preserves the first end. The remedy is to bind again and end THAT session with the prose. Putting a label in `handoff` is merely untidy: the row lacks its label and the text reaches the next driver anyway. Written BEFORE the session ends, and a failed write REFUSES the end (HANDOFF_WRITE_FAILED) rather than ending anyway: a still-bound worker is recoverable — retry, or end without a handoff deliberately — while an ended session whose handoff evaporated is not, because the context that composed it is gone. Passing `handoff` on a session with no worker is refused rather than dropped; there is no sequence to write it to. #1956: `resumeClaim: true` also writes a resume claim, after the handoff and before the end, so the fresh context of a rotation starts this worker's next session with resumeSession and no arguments (see createResumeClaim). Only on your own open worker session: otherwise it refuses and nothing ends.
id ID!
summary String
handoff String
inputTokens Int
outputTokens Int
turnCount Int
errorCount Int
resumeClaim Boolean
createResumeClaim ResumeClaimReceipt! #1956 (hrn:node:hadronmemory.com:specs:cor:agt:020:03) — write a RESUME CLAIM for your own open worker session before a deliberate context reset that keeps the session (a shed). The fresh context recovers the worker with resumeSession and no arguments, so no binding file is needed. The claim is single use, lives 60 seconds from this write (Holger, #12291), is redeemable only by you (judged by your token, never by anything presented), and replaces any unused claim for the same session. For a rotation, pass endSession(resumeClaim: true) instead, which writes it with the handoff, before the end. Someone else's session answers as an absent one; an ended session refuses SESSION_ENDED; a session with no worker refuses SESSION_NOT_WORKER_BOUND. An App key without a user or an impersonation caller receives the same absent-session answer.
sessionId ID!
resumeSession ResumeSessionResult! #1956 (hrn:node:hadronmemory.com:specs:cor:agt:020:03) — recover your worker binding after a context reset, with one call and no arguments. One unused resume claim of yours binds it (RESUMED to the open session, or STARTED: the worker's next session, when the claimed one had ended); several list as CHOOSE and consume nothing. With no claim, the fast path: exactly one of your worker sessions that reads LIVE is RESUMED, several list as CHOOSE, never a guess. Pass `session` to pick a listed candidate. Nothing at all refuses NOTHING_TO_RESUME, and nothing is posted or recorded on your behalf. Judged only on your own user: anyone else's claims and sessions are invisible, and an App key or an impersonation gets the same refusal as a caller with nothing. A claim is single use: of two racing redemptions one binds and the other refuses NOTHING_TO_RESUME, and a claim's 60 seconds are judged by the database clock when it is consumed. A claim is recovery intent, not a waiver: resuming an open session passes the same lifecycle gate as any resume (you still hold the name and may drive its App, it is not past its hard expiry or dormant, no other session of the worker is live), else RESUME_REFUSED; starting the next one passes startSession's. Either refusal spends the claim. More recently driven worker sessions than one scan holds refuses RESUME_AMBIGUOUS rather than guessing.
input ResumeSessionInput
recordUsage Boolean! Record a usage event. A supplied session is attributed only when owned by the caller (no admin or impersonation bypass). Missing, deleted or unowned session references are recorded without session attribution. Owned ended, expired or idle sessions accept late attribution without counting it as activity. The existing READER role gate still applies.
event UsageEventInput!
regenerateAppKey AppCreated! App key management — revoke all active keys for an App and mint a fresh one. Only whoever manages the App, as themselves (hrn:node:hadronmemory.com:specs:cor:dmo:050:05; hrn:node:hadronmemory.com:specs:cor:acl:010:01). Person-only (hrn:node:hadronmemory.com:specs:cor:dmo:050:12, #3277): never a worker session in any shape, a run principal, an impersonation or an App key, even when the worker's holder manages the App. The replacement key holds no scopes. Accepts the entity's ID or URN.
appRef ID!
updateMyProfile User! Update display name and handle. A supplied email must match the existing address (ignoring case and surrounding whitespace); it is not rewritten or cleared by this call.
name String
handle String
email String
updateUserRoles User!
userId ID!
roles [Role!]!
mergeUsers User! Consolidate a duplicate account into a surviving user. Source-only identities and relationships move; duplicate role-bearing relationships preserve the strongest live entitlement. The source is soft-deleted. Requires platform administration, both accounts' consent proof, and an unbound user JWT; API keys, Apps, impersonation and session-bound callers cannot authorize a merge. The platform-role and missing-proof checks run before the credential-shape check. The resulting merge is global; organization administration does not authorize account consolidation. Both accounts must approve the exact ordered pair after fresh login, within 15 minutes. The proof is single-use, consumed atomically before transfers, and recorded with the merge. Invalid or missing proof refuses MERGE_CONSENT_REQUIRED. There is no administrator substitute or recovery path. Records the merge (#1715). User ids stored inside decisions and decision logs are never rewritten, since they are authenticated; readers follow them to the surviving account, so it is the asker or decider they name. Refused with MERGE_USER_IN_OPEN_ALARMS (extension alarmCount; never the alarms, tasks or Apps, which the caller may not be able to read) while either account is named in the owner chain of an unacknowledged agent-task alarm, whose sealed chain cannot follow a merge yet. Acknowledge the alarms, then merge. A source account with an unrevoked passkey refuses MERGE_SOURCE_HAS_PASSKEYS; revoke those passkeys before merging.
input MergeUsersInput!
beginMergeUsersConsent UserMergeConsentRequest! A platform admin using an unbound user JWT begins an exact ordered-pair, full-consolidation consent, valid for 15 minutes; API keys, Apps, impersonation and session-bound callers refuse FORBIDDEN. Returns its opaque proof once.
source String!
target String!
approveMergeUsersConsent Boolean! Each account approves with its own JWT from a verified login at or after consent creation (millisecond resolution). API keys, Apps, impersonation and any session-bound caller cannot approve. Source and target name the exact ordered pair. No admin substitute.
proof String!
source String!
target String!
deleteUser Boolean! Delete a user account (self-serve account deletion, Apple 5.1.1(v) / GDPR erasure posture). Requires a user credential (JWT or hdr_user key); App-key callers are rejected. Omitting userRef (or passing null) deletes the CALLER's own account (no role needed). A userRef that is supplied but empty after trimming is refused with BAD_USER_INPUT for every caller and deletes nothing (hrn:node:hadronmemory.com:specs:cor:aut:020:03). A platform ADMIN/OWNER may name another user; userRef accepts the user's ID, handle, or hrn:user:<handle> URN. Any other caller naming a target receives the same FORBIDDEN error whether or not that user exists (no user-enumeration oracle). Deleting another user also requires a reason of 1-500 Unicode code points after trimming (BAD_USER_INPUT otherwise); this check follows target authorization. Org memberships auto-resolve: an org where the target is the only active OWNER but which still has OTHER active members BLOCKS deletion (error code SOLE_ORG_OWNER, extensions.organizations lists the blockers - transfer ownership first, nothing is deleted); an org where the target is the ONLY active member is soft-deleted with the account; plain memberships are revoked. Owned data is hard-erased: personal/private and user-owned memories, user-owned Apps and Agents (with their standard delete cascades), sessions, OAuth/handoff codes, provider connections, grants, shares, subscriptions, widgets and user secrets; API keys are revoked. The User row itself is kept for audit/billing FK integrity but scrubbed (identity fields nulled, handle replaced with a random deleted-... value) and soft-deleted; a deleted account can no longer authenticate.
userRef ID
reason String
createOrganization Organization!
name String!
urn String!
updateOrganization Organization! Update an Organization. Accepts the entity's ID or URN.
id ID!
name String
urn String
listedOnMarketplace Boolean
policy JSON
deleteOrganization Boolean! Soft-delete an Organization. Accepts the entity's ID or URN.
id ID!
linkGithubApp Organization! Link a GitHub App installation to an organization (org ADMIN or platform ADMIN). Accepts the entity's ID or URN.
orgId ID!
installationId Int!
updateOrgGithubApp Organization! Set GitHub App credentials for an organization (encrypted at rest). Accepts the entity's ID or URN.
orgId ID!
appId String!
privateKey String!
unlinkGithubApp Organization! Remove all GitHub App config from an organization. Accepts the entity's ID or URN.
orgId ID!
createUserInvitation UserInvitation! User invitations (org ADMIN or platform ADMIN). Accepts the entity's ID or URN. Limits (#2984): expiresInDays is a whole number from 1 to 10 and maxActivations from 2 to 1000; omitted or null means 10 days and two activations (Holger V49). 0, negatives, an explicit 1 for maxActivations and larger values are refused as BAD_USER_INPUT (hrn:node:hadronmemory.com:specs:cor:api:260:01), judged after the org-admin gate.
orgId ID!
memberRole Role!
name String
email String
githubUsername String
maxActivations Int
expiresInDays Int
inviteUser UserInvitation! Platform invite — no org association, just onboards a new user Limits (#2984): expiresInDays is a whole number from 1 to 10 and maxActivations from 2 to 1000; omitted or null means 10 days and two activations (Holger V49). 0, negatives, an explicit 1 for maxActivations and larger values are refused as BAD_USER_INPUT (hrn:node:hadronmemory.com:specs:cor:api:260:01).
name String
email String
githubUsername String
maxActivations Int
expiresInDays Int
acceptInvitation Boolean! Accepts an invitation by its acceptance slug (not its id). Refusals are typed: NOT_FOUND for an unknown slug, an id supplied as the slug, or a revoked-by-removal invitation; UNAUTHENTICATED when signed out; BAD_USER_INPUT for an expired invitation or one whose issuer lost the authority to invite; CONFLICT when the invitation has reached its maximum uses or the caller already accepted it. A refusal changes nothing.
slug String!
addOrgMember OrgMember! Accepts the entity's ID or URN (orgId). A user who is already a live member is refused with CONFLICT.
orgRef String #764 — the organization as an id / slug / hrn:org:<slug> URN. Supply this OR orgId.
orgId ID

⚠️ DEPRECATED

Use orgRef (accepts id / slug / URN).
userRef String #764 — the user as an id / email / handle / hrn:user:<handle> URN. Supply this OR userId.
userId ID

⚠️ DEPRECATED

Use userRef (accepts id / email / handle / URN).
role Role!
updateOrgMember OrgMember! Accepts the entity's ID or URN (orgId). Refused with NOT_FOUND when the user is not a live member, and with CONFLICT when it would demote the organization's last live owner.
orgRef String #764 — the organization as an id / slug / hrn:org:<slug> URN. Supply this OR orgId.
orgId ID

⚠️ DEPRECATED

Use orgRef (accepts id / slug / URN).
userRef String #764 — the user as an id / email / handle / hrn:user:<handle> URN. Supply this OR userId.
userId ID

⚠️ DEPRECATED

Use userRef (accepts id / email / handle / URN).
role Role!
removeOrgMember Boolean! Accepts the entity's ID or URN (orgId). Refused with NOT_FOUND when the user never held a membership, and with CONFLICT when it would remove the last live owner; removing an already-revoked member succeeds again.
orgRef String #764 — the organization as an id / slug / hrn:org:<slug> URN. Supply this OR orgId.
orgId ID

⚠️ DEPRECATED

Use orgRef (accepts id / slug / URN).
userRef String #764 — the user as an id / email / handle / hrn:user:<handle> URN. Supply this OR userId.
userId ID

⚠️ DEPRECATED

Use userRef (accepts id / email / handle / URN).
createMemory Memory! Create a free-standing memory. orgId accepts an organization's ID or URN. With orgId, the default is knowledge-class with ORGANIZATION visibility; knowledge/group creation requires the org's memory.create grant. Omitting orgId (or passing null) creates a user-owned memory in the authenticated caller's namespace and requires an explicit personal/private memoryClass. The default knowledge class is refused without orgId. Pass memoryClass: group + visibility: GROUP for a group-class memory (023-app-shape US4; the caller is auto-added as the first owner), or memoryClass: personal | private for an owner-only memory the caller owns (free-standing, no app/agent). An org-anchored personal/private memory requires actual membership of that org container; the org-less owner-only path requires no org membership. system- and app-class memories are NOT created here — they auto-provision via Agent.systemMemoryId / the App install path.
orgId ID Owning organization. OPTIONAL (spec 047 — user-owned tenancy): when OMITTED, the memory is owned by the authenticated caller in their own handle namespace (organizationId NULL, ownerUserId = caller), and its URN roots on the caller's handle (hrn:mem:<handle>:<slug>) rather than an org domain. The org-less path supports only the owner-only classes 'personal' and 'private'; pass orgId for 'knowledge' / 'group'.
name String!
shortDescription String
description String
data JSON Free-form structured metadata bag (client-defined JSON). Null = unset.
tags [String!]
license String
category0 String
category1 String
category2 String
iconUrl String
heroUrl String
homeUrl String
source String
readBranch String
writeBranch String
visibility MemoryVisibility
memoryClass MemoryClass 'knowledge' (default), 'group', or the owner-only 'personal' / 'private'. Without orgId, only personal/private are accepted; the knowledge default is refused. 'system' and 'app' are rejected here and auto-provision via different code paths.
vectorIndexEnabled Boolean Override the vector-index defaults. A 'knowledge'-class memory defaults to vectorIndexEnabled=true with embeddingSource=contentChunks (so any node with content is retrievable immediately, no abstract authoring needed — #281); every other class keeps the column defaults (false / abstract). An explicit value here wins for any class.
embeddingSource EmbeddingSource
maxRevCount Int #621 — per-node revision-history cap (default 10, minimum 1).
draftCorpus Boolean #1447/#1448 — accepted for compatibility and ignored since #1591: minting is per node, and every new node starts unminted, with draft rights, in any memory.
createAppMemory Memory! Create a NEW free-standing app-class memory in an App with at least one installed Agent. The caller must act as themselves, outside a worker/session, App-key, headless-run or impersonation principal, through the existing org ADMIN/OWNER gate, or as the actual owner of a user-owned App. App participants read and write it; the installed Agent's owning org gains no access. Existing memories cannot be attached through this operation. Name determines the slug as createMemory does. Refusals: FORBIDDEN, AGENT_NOT_INSTALLED, BAD_USER_INPUT (empty name). Installation and tenant ownership/membership are checked in the inserting transaction, fenced against transfer, uninstall and revocation. See hrn:node:hadronmemory.com:specs:cor:acl:010:01.
appRef ID!
name String!
shortDescription String
description String
tags [String!]
createMemoryInApp Memory! Add a NEW memory to an App, born App-scoped. Unlike createMemory (which only makes free-standing memories), this scopes the new memory to an App. memoryClass accepts only the App-associable classes: 'app', 'knowledge', 'personal', or 'private'. This door rejects 'system' and 'group'; this is its allowlist, not a claim that the database forbids app_id for every rejected class. appRef/agentRef accept an ID, bare URN, or prefixed URN; the Agent must be installed in the App. Authorization is split by class: 'app'/'knowledge' are shared data and require the App's user-owner or owning-org OWNER/ADMIN. Personal/private require the caller's actual App membership (the caller becomes the owner), with no platform-admin membership bypass; they are not yet supported for a user-owned App. The install is rechecked as live and licensed in the deciding transaction. Live name collisions are aliased to a free URN. Typed errors: UNSUPPORTED_MEMORY_CLASS, BAD_USER_INPUT (maxRevCount < 1), APP_UNINSTALLED, AGENT_NOT_INSTALLED, MEMORY_URN_CONFLICT, FORBIDDEN, UNAUTHENTICATED.
appRef ID!
agentRef ID!
memoryClass MemoryClass!
name String!
shortDescription String
description String
data JSON
tags [String!]
vectorIndexEnabled Boolean
embeddingSource EmbeddingSource
maxRevCount Int
attachMemoryToApp Memory! Attach an EXISTING free-standing memory to an App. Applies only to 'personal'/'private' memories owned by the caller (an 'app'-class memory can't be free-standing, so there is nothing to attach). Sets the App and Agent scope; the memory's URN, class, and owner are unchanged. memoryRef/appRef/agentRef accept an ID, bare URN, or prefixed URN; the Agent must be installed in the App. Requires App membership. Typed errors: UNSUPPORTED_MEMORY_CLASS, MEMORY_ALREADY_APP_SCOPED, APP_UNINSTALLED, AGENT_NOT_INSTALLED, FORBIDDEN, ORGANIZATION_MISMATCH.
memoryRef ID!
appRef ID!
agentRef ID!
updateMemory Memory! Update a Memory. Accepts the entity's ID or URN. Spec 033 FR-026: enabling `vectorIndexEnabled` on an `isEncrypted` memory requires `acknowledgeVectorInversionRisk: true` in the same call. Without the flag, an `EncryptedVectorIndexNotAcknowledgedError` is thrown carrying the full four-point disclosure on `error.disclosure` (single source of truth in `FR_026_DISCLOSURE` — see `src/lib/entityRef/errors.ts`). On a non-encrypted memory the flag is a no-op.
id ID!
name String
urn String
organizationId ID
shortDescription String
description String
data JSON
tags [String!]
license String
category0 String
category1 String
category2 String
iconUrl String
heroUrl String
homeUrl String
source String
readBranch String
writeBranch String
visibility MemoryVisibility
listedOnMarketplace Boolean
vectorIndexEnabled Boolean
embeddingSource EmbeddingSource
acknowledgeVectorInversionRisk Boolean
chunkTokens Int
chunkOverlap Int
forceFixedSize Boolean
maxRevCount Int
schema JSON
transferMemoryOwnership MemoryOwnerTransferPreview! Transfer a free-standing Memory to exactly one new owner. dryRun previews the new URN and dependent handling without writing; apply recomputes under lock and can pin the preview with expectedNewUrn. A class change across user/org ownership must be explicit. The caller needs authority on both sides; unreadable source memories are concealed as not found. Group members block transfer by default; resetGroupMembers explicitly revokes every old membership inside the transfer transaction. A group destination then adds the caller as its first owner-member.
memoryRef ID!
orgRef ID
userRef ID
targetClass MemoryClass
expectedNewUrn String
resetGroupMembers Boolean
dryRun Boolean
retryFailedEmbeddings Int! #882 — re-drive every FAILED embed in a memory (the operator recovery surface; previously hand-written SQL). Re-stamps each live node whose `embeddingFailedAt` is set — permanent-class failures whose pending marker was cleared, and backed-off retryable failures (made immediately eligible) — resetting the failure state exactly like a fresh write, then wakes the embedding worker. Returns the count re-stamped; 0 when the memory is not vector-indexed. `memoryRef` accepts the memory's ID or URN. Requires memory-owner or org-ADMIN (same gate as updateMemory).
memoryRef ID!
deleteMemory Boolean! Soft-delete a Memory. Accepts the entity's ID or URN.
id ID!
cloneMemory Memory! Clone a Memory into a new Memory at `targetUrn`. `ref` accepts the source's ID or URN. `targetUrn` is a fully-qualified "root:slug" memory URN naming the clone; its org segment MAY differ from the source's, cloning the memory into another organization. The clone's display name is derived from the target slug. Copies the Memory row and its eligible live graph. Comment nodes, compiled boot-prompt nodes and decision-family nodes are excluded; derived INCLUDE edges are re-derived rather than copied. References to the source memory's URN inside node content/abstract (canonical and legacy spellings) are rewritten to the clone's URN. Vector-index config carries over and the clone's nodes are stamped for re-embedding. NOT copied: revision history, subscriptions, shares, group members (the caller is bootstrapped as a group clone's first owner), sessions, licenses, log entries, assets, and git-sync config (the clone starts DB-only). Include tags (#2167; hrn:node:hadronmemory.com:specs:cor:dmo:150:04 and hrn:node:hadronmemory.com:specs:cor:dmo:150:06): every tag in every copied node counts as added, checked after the URN rewrite. A tag whose target is missing or that the caller can't read refuses with INCLUDE_TARGET_UNAVAILABLE. A tag that closes a cycle among the copied nodes refuses with INCLUDE_CYCLE, at any chain length. Either refusal names only the authored tag and nothing is created. Authorization: the SOURCE side requires (personal/private → owner only; knowledge/group → source-org memory.clone grant). When `targetUrn` names a DIFFERENT org, the caller must additionally be a non-reader member of that target org. system/app-class sources and encrypted memories are rejected.
ref ID!
targetUrn String!
extractParentNodeToMemory Memory! Extract a parent node and its whole loc-subtree into a BRAND-NEW memory, making the parent the new memory's root. The subtree is loc-prefix defined: the node at the parent's loc plus every live descendant (loc starting with 'parentLoc:'). Locs are REBASED so the parent becomes the root — 'findings:auth' becomes the memory slug and 'findings:auth:oauth' becomes '<slug>:oauth'. Edges wholly inside the subtree carry over (their loc re-derived from the rebased endpoints); boundary-crossing edges and PendingEdges are dropped. 'parentRef' is the parent node's ID or fully-qualified URN. 'targetUrn' is a fully-qualified '<root>:<slug>' URN naming the new memory (it may land in a DIFFERENT org). 'move' = false (default) COPIES the subtree, leaving the source intact; 'move' = true relocates it, soft-deleting the source subtree (its nodes, the source memory's touching edges, and its pending edges). The new memory PRESERVES the source's class: group stays group (the caller is bootstrapped as its first owner), personal/private stays owner-owned, and knowledge stays knowledge. Class preservation alone is not a claim that the new memory has an identical membership audience. Governance/config (requiresLicense, chunk dials, revision cap, acceptsUploads) carries over from the source. Authorization: read access to the source memory (denial reads as NODE_NOT_FOUND). For knowledge/group sources the caller needs the SOURCE org's memory.clone grant (an export) AND the destination org's memory.create (plus a non-reader membership for a cross-org drop); a personal/private extract instead requires the owner to be a member of the destination org. 'move' additionally requires source write access and must leave a live node outside the extracted subtree; otherwise it would empty the source (clone + deleteMemory instead). The guard uses node membership, not the source memory's mutable name. Encrypted and system/app-class sources are rejected. Include tags (#2167; hrn:node:hadronmemory.com:specs:cor:dmo:150:04 and hrn:node:hadronmemory.com:specs:cor:dmo:150:06): every tag in every copied node counts as added and is resolved where it lands in the new memory. First, a tag naming a copied node is rewritten to that node's rebased loc (a URN tag to the source memory becomes the new memory's URN); only the target changes, and a rewritten node loses its contentHash and authorship. A tag naming anything else stays as written, so a relative tag naming a node left behind refuses with INCLUDE_TARGET_UNAVAILABLE (a URN tag to a memory the copier can read passes unchanged). A relative tag outside the subtree whose loc equals a rebased loc also refuses (R188), and is never rewritten. A tag that closes a cycle refuses with INCLUDE_CYCLE. Either refusal names the tag as it stands in the copy, and nothing is created or moved. v1 limitation: apart from include tags, node content is copied verbatim — because both the slug and node locs change, other URN references among the moved nodes WILL break; and unresolved PendingEdges within the subtree are dropped.
parentRef ID!
targetUrn String!
move Boolean
setMemorySourceToken Memory! Set encrypted source token for non-GitHub-App repos. Accepts the entity's ID or URN.
id ID!
token String!
expiresAt String
createAgent Agent! Create an agent. Provide orgId to create an ORG-owned agent (requires org ADMIN); OMIT orgId to create a USER-OWNED agent owned by the caller — its URN is rooted on the caller's bare handle (hrn:agent:<handle>:<slug>, grammar v2 — no @ sigil) and its system memory is user-owned too. Exactly one owner (org XOR user). personaRole is the persona dressing (hrn:node:hadronmemory.com:specs:cor:agt:020:01), the reusable role. A new Agent has no boot prompt: write its boot:source, compile it and approve the compiled revision (hrn:node:hadronmemory.com:specs:cor:agt:040:10, hrn:node:hadronmemory.com:specs:cor:agt:040:12). The NAMED identity is a Worker, cast with castWorker; names never live on agents. orgId accepts the org's ID or URN.
orgId ID
name String!
description String
systemMemoryId String
visibility AgentVisibility
type AgentType
surfaces [String!]
personaRole String
usesTasks Boolean
resetContextAfterTask Boolean
lifecycle AgentLifecycle #4224: omitted or null is LONG_LIVED.
contextCap Int #4225: the context cap in tokens, a whole number from 1; omitted or null is no cap.
memberRoles [String!] #2171 (R211): the member roles the Agent offers. Omitted: owner and member. Empty or malformed: BAD_USER_INPUT.
cloneAgent Agent! Clone an Agent into an organization you administer: a new PERSONAL-draft Agent with its own copy of the source's system memory, its links and imports, and a recorded origin. Needs a PUBLIC source, or one you manage in its own organization. Refusals are typed (AGENT_NOT_PUBLIC, CLONE_*); a source that keeps changing answers CONFLICT with reason AGENT_CLONE_SOURCE_CHANGED (retryable). target must be an organization. Copied: name, description, type, surfaces, usesTasks, registerDefaults, installationPolicy, memoryProvisioning, personaRole; the system memory graph (nodes, edges, pending edges) with the tasks and processes index pointers remapped; memory links (kept as links, not copied); imports and the base, re-pointed. NOT copied: visibility (the clone is PERSONAL), AI service config, boot-prompt pointers, node comments, decisions and decision logs, compiled boot-prompt nodes, derived include edges (re-derived), node revision history, embeddings (re-stamped), assets (their bytes stay with the source), git-sync config, the editor lock and published-revision pointer, Worker castings, App installs, and the source organization's subscriptions and grants. A base or import is licensed for the TARGET organization at clone time, or the clone refuses (CLONE_BASE_UNUSABLE, CLONE_IMPORT_UNUSABLE). A refusal's blocker subjects carry a name only when you can read the subject; otherwise only a position. The clone's origin is Agent.clonedFromAgentRef.
source ID!
target ID!
name String
slug String
updateAgent Agent! Update an Agent. urn renames the slug (org-owned agents only). personaRole is normalized (explicit null or blank clears, omitted preserves). Worker castings referencing this agent are unaffected — the named identity lives on the Worker. Accepts the entity's ID or URN.
ref ID!
name String
urn String
description String
systemMemoryId String
visibility AgentVisibility
listedOnMarketplace Boolean
type AgentType
surfaces [String!]
personaRole String
usesTasks Boolean
resetContextAfterTask Boolean
lifecycle AgentLifecycle #4224: omitted or null leaves it unchanged.
contextCap Int #4225: the context cap in tokens, a whole number from 1; omitted leaves it, null clears it (no cap).
registerDefaults RegisterDefaultsInput
memberRoles [String!] #2171 (R211): replaces the member roles the Agent offers (and nothing else in its installation policy). Omitted or null: unchanged. Empty or malformed: BAD_USER_INPUT. Existing members keep their role.
deleteAgent Boolean! Soft-delete an Agent and its owned system memory. Requires management access to the readable Agent. Refuses while a live App install or live parent Agent import references it, or a live Agent extends it as its base. AgentMemoryItem attachments do not block deletion. Also refused with DECISION_CONTAINED (#1641) while the Agent's system memory holds a decision or a decision log: removing the memory would remove them, so the Agent is kept. Decision protection always applies. If this server requires minted content to be retained, its separate deletion restrictions also apply. See hrn:node:hadronmemory.com:specs:cor:dmo:050:14. Accepts the entity's ID or URN.
ref ID!
setAgentBase Agent! #1885 (hrn:node:hadronmemory.com:specs:cor:dmo:050:14) - set, change or clear the one base Agent this Agent extends. The Agent then inherits its base chain's system-memory nodes, except boot prompts. A null baseRef clears the base. Whoever manages this Agent may call it. Extending another organization's Agent needs the organization's active AgentOrgGrant for it (a same-org base provisions one, never reactivating a revoked grant); a user-owned Agent extending someone else's needs its owner's active AgentSubscription. Refused, changing nothing, with AGENT_BASE_CYCLE when the base is this Agent or extends it, and AGENT_BASE_CHAIN_TOO_LONG when a chain through this Agent, its own or any Agent's that extends it, would hold more than 4. Accepts each Agent's ID or URN.
ref ID!
baseRef ID
setAgentIndexRefs Agent! #1892 (hrn:node:hadronmemory.com:specs:cor:dmo:050:15, hrn:node:hadronmemory.com:specs:cor:dmo:050:16) - set or clear this Agent's tasks-index and processes-index pointers. An omitted argument leaves that pointer unchanged; null clears it. Each target is a node ID or fully-qualified URN, and must be a live node the caller may read (refused as NODE_NOT_FOUND otherwise). Whoever manages this Agent may call it. Accepts the Agent's ID or URN.
ref ID!
tasksIndexRef ID
processesIndexRef ID
repairAgentSystemMemory Agent! #949 — re-own an Agent's class=system memory to the Agent's own owner (org XOR user). On an ownership repair, attempt the derived '<agent-urn>-system' URN; if another live memory holds it, retain the current URN. A changed URN records an alias. An already-consistent owner pair returns without changing its URN. The recovery path for a system memory that ended up owned by a different tenant. Access to a memory follows the MEMORY's owner, so such a row puts one tenant's Agent design inside another tenant's audience. System memories are only ever created by Agent provisioning, so before this the only fix was to recreate the Agent. Authorization: PLATFORM ADMIN only — the row being moved belongs to a different tenant than the Agent, so neither side's org admin is the right authority. Idempotent: an already-consistent pair is a no-op. Error codes (extensions.code): FORBIDDEN, AGENT_HAS_NO_SYSTEM_MEMORY, SYSTEM_MEMORY_NOT_FOUND. Accepts the entity's ID or URN.
agentRef ID!
addMemoryToAgent Agent! Attach a Memory to an Agent. #3253 (hrn:node:hadronmemory.com:specs:cor:dmo:050:09): a live subscription of the Agent's org admits a cross-tenant link up to its level (READER read, CONTRIBUTOR read-write). The caller must hold that capability. Activation and license add no check beyond the memory read gate. Accepts the entity's ID or URN.
agentRef ID!
memoryRef ID!
role String
updateAgentMemoryRole Agent! Update an Agent's role on an attached Memory. #3253 (hrn:node:hadronmemory.com:specs:cor:dmo:050:09): the same subscription, caller-capability, class and PUBLIC-Agent gates apply as on addMemoryToAgent. Accepts the entity's ID or URN.
agentRef ID!
memoryRef ID!
role String!
removeMemoryFromAgent Agent! Detach a Memory from an Agent. Accepts the entity's ID or URN.
agentRef ID!
memoryRef ID!
createMemorySubscription MemorySubscription! Create a cross-org Memory subscription. Accepts the entity's ID or URN.
memoryRef String #764 — the memory as an id or URN. Supply this OR memoryId.
memoryId ID

⚠️ DEPRECATED

Use memoryRef (accepts id / URN).
orgRef String #764 — the organization as an id / slug / hrn:org:<slug> URN. Supply this OR orgId.
orgId ID

⚠️ DEPRECATED

Use orgRef (accepts id / slug / URN).
role Role!
createAgentOrgGrant AgentOrgGrant! Subscribe an organization to a PUBLIC Agent without creating an App. Accepts the entity's ID or URN.
agentRef ID!
orgRef ID!
revokeAgentOrgGrant AgentOrgGrant! Revoke an organization's Agent subscription without deleting install state. Accepts the entity's ID or URN.
agentRef ID!
orgRef ID!
updateMemorySubscription MemorySubscription! Update a cross-org Memory subscription. Accepts the entity's ID or URN.
memoryRef String #764 — the memory as an id or URN. Supply this OR memoryId.
memoryId ID

⚠️ DEPRECATED

Use memoryRef (accepts id / URN).
orgRef String #764 — the organization as an id / slug / hrn:org:<slug> URN. Supply this OR orgId.
orgId ID

⚠️ DEPRECATED

Use orgRef (accepts id / slug / URN).
role Role!
deleteMemorySubscription Boolean! Delete a cross-org Memory subscription. Accepts the entity's ID or URN.
memoryRef String #764 — the memory as an id or URN. Supply this OR memoryId.
memoryId ID

⚠️ DEPRECATED

Use memoryRef (accepts id / URN).
orgRef String #764 — the organization as an id / slug / hrn:org:<slug> URN. Supply this OR orgId.
orgId ID

⚠️ DEPRECATED

Use orgRef (accepts id / slug / URN).
syncMemory Memory! Trigger an on-demand sync for one memory (org ADMIN or CONTRIBUTOR). Refuses SYNC_NOT_ATTEMPTED with reason NO_SOURCE or NO_INSTALLATION when no sync can be attempted; no sync status, timestamp or report is written. Access is checked first; encrypted-memory refusal is unchanged. Accepts the entity's ID or URN.
id ID!
pushMemoryToGit Boolean! Push all nodes in a memory to its configured git repo. Accepts the entity's ID or URN.
id ID!
deleteExchangeConnection Boolean!
id ID!
testExchangeConnection Boolean!
id ID!
startConnection ConnectionStart! Start the OAuth flow that connects a mailbox, calendar or Drive to an org (#2897; hrn:node:hadronmemory.com:specs:cor:api:240:02). The same start as POST /auth/{provider}/start, which stays for the portal: the same org-ADMIN gate and the same single-use, provider-bound nonce. A flow started here ends on a page the server hosts, not on the portal. Only a signed-in user acting as themselves may call it: a portal sign-in or a user API key, who is an ADMIN of orgRef (ID or URN). An App key, a bound worker session, an impersonated request and an OAuth credential limited to the MCP surface are refused, because this mints a credential-bearing start for a person's mailbox, calendar or Drive (hrn:node:hadronmemory.com:specs:cor:dmo:050:05). A caller who is not an ADMIN, and an unknown org, get the same Forbidden. An unconfigured provider is CONNECTION_PROVIDER_NOT_CONFIGURED.
provider ConnectionProvider!
orgRef ID!
createSlackConnection SlackConnection! Register a Slack workspace install (spec 043). orgRef/appRef accept ID or URN (cor:api:140); the App must belong to the org. Both tokens are validated live by the tool and stored encrypted THERE — core keeps identity only, and no field ever returns a token. Requires org ADMIN/OWNER.
orgRef ID!
appRef ID!
botToken String!
appToken String!
deleteSlackConnection Boolean! Soft-delete a Slack connection (org ADMIN/OWNER); tears down the tool side best-effort.
ref ID!
createMcpServer McpServer! Register an external MCP server (org ADMIN/OWNER). orgRef accepts ID or URN (cor:api:140). headers is a JSON object of static request headers (e.g. Authorization) — encrypted at rest, write-only, never returned. Registration grants nothing by itself: runs still need the policy chain to allow tool.mcp__<slug>__<tool>.
orgRef ID!
slug String!
name String!
url String!
headers JSON
toolAllowlist [String!]
enabled Boolean
updateMcpServer McpServer! Update a registered MCP server (org ADMIN/OWNER). The slug is immutable — flow nodes reference it in data.tools names. headers REPLACES the stored object; clearHeaders: true removes it (pass one or the other, not both).
ref ID!
name String
url String
headers JSON
clearHeaders Boolean
toolAllowlist [String!]
enabled Boolean
deleteMcpServer Boolean! Hard-delete a registered MCP server (org ADMIN/OWNER); runs referencing its tools fail loud afterwards.
ref ID!
cancelWebPoll CancelWebPollPayload! Stop one of the organization's page-monitor watches (#1562; org ADMIN/OWNER, tool.web_poll policy). A job id from another organization, or none, answers NOT_FOUND. Cancelling a stopped watch succeeds with alreadyCancelled.
orgRef ID!
jobId ID!
createSecret Secret! Create a named, owner-scoped secret (#677). Gate per owner scope: user -> that user (ownerRef optional, defaults to the caller); org -> org ADMIN; app -> any member of the App, as a person (an App key, an impersonated session and a run are refused; the value is stored as version 1). value is the secret payload — encrypted at rest, write-only, never returned; at most 32 KiB of stored JSON, counted in bytes. kind selects validation: generic (opaque JSON) or webfetch-auth ({type: bearer|basic|header, ...} + metadata.urlPrefix origin binding). A run resolves the name via the CSS cascade (user -> org) at entitled scopes only; an App secret is never resolved by a run (hrn:node:hadronmemory.com:specs:cor:sec:020:02).
ownerType String!
ownerRef ID
name String!
kind String!
metadata JSON
value JSON!
updateSecret Secret! Change a secret's value and/or metadata. For an org or user secret a value OVERWRITES (no versions). For an App secret a value ADDS the next version and never overwrites (hrn:node:hadronmemory.com:specs:cor:sec:010:03); any member of the App may store. Name, kind, and owner are immutable — the cascade and flow config reference the name; create a new name instead. The effective (metadata, value) pair is re-validated per kind.
ref ID!
metadata JSON
value JSON
deleteSecret Boolean! Hard-delete a secret, every version with it; referencing runs fail their resolution loud (or fall through the cascade) afterwards. An unprotected App secret is deleted by its creator or whoever manages the App, each as a person.
ref ID!
createHomeAssistantInstance HomeAssistantInstance! Register a Home Assistant instance (org ADMIN/OWNER). orgRef accepts ID or URN (cor:api:140). accessToken is an HA long-lived access token — encrypted at rest, write-only, never returned. Registration grants nothing by itself: runs still need the policy chain to allow tool.ha__<slug>__<op>.
orgRef ID!
slug String!
name String!
url String!
accessToken String!
opAllowlist [String!]
enabled Boolean
updateHomeAssistantInstance HomeAssistantInstance! Update a registered Home Assistant instance (org ADMIN/OWNER). The slug is immutable — flow nodes reference it in data.tools names. accessToken REPLACES the stored token (never cleared: an instance without a token is unusable).
ref ID!
name String
url String
accessToken String
opAllowlist [String!]
enabled Boolean
deleteHomeAssistantInstance Boolean! Hard-delete a registered Home Assistant instance (org ADMIN/OWNER); runs referencing its ops fail loud afterwards.
ref ID!
createResendSender ResendSender! Register one BYO Resend sender for an org. The API key is encrypted and never returned.
orgRef ID!
from String!
apiKey String!
enabled Boolean
updateResendSender ResendSender! Update the fixed sender, replace its write-only API key, or enable/disable it.
ref ID!
from String
apiKey String
enabled Boolean
deleteResendSender Boolean! Hard-delete an org's BYO Resend sender.
ref ID!
exchangeReply Boolean!
connectionId ID!
messageId ID!
body String!
exchangeMoveMessage Boolean!
connectionId ID!
messageId ID!
folderId String!
emailSaveDraft EmailDraftInfo! Save a draft in the mailbox's own Drafts folder (spec 002 US5): either a reply-draft (replyToMessageId) or a fresh draft (to + subject). Owner-only. idempotencyKey makes retries safe (at-least-once callers).
connectionRef ID!
replyToMessageId ID
to [String!]
subject String
bodyHtml String!
idempotencyKey String
emailUpdateDraft Boolean! Update a provider-side draft's body. Owner-only.
connectionRef ID!
draftId ID!
bodyHtml String!
emailSendDraft Boolean! Send a provider-side draft. Owner-only; idempotencyKey makes retries safe.
connectionRef ID!
draftId ID!
idempotencyKey String
emailDeleteMessage Boolean! Delete a message (provider trash semantics). Owner-only.
connectionRef ID!
messageId ID!
emailMarkRead Boolean! Mark a message read or unread (default read). Owner-only.
connectionRef ID!
messageId ID!
isRead Boolean
emailFlagMessage Boolean! Flag, unflag, or complete a message (default FLAGGED). Owner-only.
connectionRef ID!
messageId ID!
flag EmailFlag
emailCategorizeMessage Boolean! Set the categories (color labels) on a message. Owner-only.
connectionRef ID!
messageId ID!
categories [String!]!
calendarCreateEvent CalendarEvent! Create an event. calendarId defaults to the primary calendar. Owner-only.
connectionRef ID!
calendarId String
title String!
description String
location String
start CalendarEventTimeInput!
end CalendarEventTimeInput!
attendees [String!] Attendee email addresses.
notifyAttendees Boolean
idempotencyKey String
calendarUpdateEvent CalendarEvent! Patch an event — absent fields stay unchanged; attendees replaces the set. Owner-only.
connectionRef ID!
eventId ID!
calendarId String
title String
description String
location String
start CalendarEventTimeInput
end CalendarEventTimeInput
attendees [String!]
notifyAttendees Boolean
idempotencyKey String
calendarDeleteEvent Boolean! Delete (cancel) an event. Owner-only.
connectionRef ID!
eventId ID!
calendarId String
notifyAttendees Boolean
idempotencyKey String
calendarRespondToEvent CalendarEvent! Set the connected account's own RSVP on an event it was invited to (ACCEPTED / DECLINED / TENTATIVE — NONE is not a settable response). Owner-only.
connectionRef ID!
eventId ID!
response CalendarEventResponse!
calendarId String
exportNodeToGoogleDoc DriveFile! Export a node's markdown as a NEW Google Doc in the connected drive (nodeRef is a PK or fully-qualified URN; title defaults to the node name; folderId defaults to the drive root). Always creates — the drive tool's scope cannot edit existing files, and no update surface exists. Owner-only: no grant scope maps to doc creation (fail-closed for App/headless callers).
nodeRef ID!
connectionRef ID!
folderId ID
title String
startChat ChatStartResult! Start an AGENT CHAT (creates chat nodes, loads conversation, returns compiled prompt). When called by a JWT user, the agent chat is created in that user's personal memory for the agent (provisioned lazily if needed). #1034: an **agent chat** — deliberately not "chat session", which is reserved for the human's own conversation and names no row in this schema, and not the **team chat**, which is the App's shared channel. Accepts the entity's ID or URN. #4039 (hrn:node:hadronmemory.com:specs:cor:cht:020:02): with no conversationName, the chat opens in the first ordinary conversation, in the author's order (Node.seq, then loc), whose data.entryCondition holds for the starter; a conversation with no condition holds. A condition that cannot be evaluated refuses with ENTRY_CONDITION_FAILED (extensions reason, messageId and detail), and nothing is created. A named start never checks a condition.
agentId ID!
userId String
conversationName String
scope ChatScope
isTestRun Boolean
llmModel String #3096 / hrn:node:hadronmemory.com:specs:cor:dmo:150:08: optional client-reported model id, at most 256 UTF-16 code units, no control/format/line-separator characters or unpaired surrogates. Omitted or null fills empty for this call. Used only for prompt text and its immutable record, labelled client-reported; never billing, quotas or authorization. Invalid input refuses BAD_USER_INPUT without echoing it.
aiConfigChoice String #3957 (hrn:node:hadronmemory.com:specs:cor:dmo:050:10): optional AI config choice for this chat, stored with it: `default` or one of the chat App's own config ids from chatAiConfigChoices. Omitted keeps what the chat has. Any other id is refused as a missing config, revealing nothing about it.
sendChatMessage ChatPromptResult! Process a user message (saves message, builds context, returns next prompt). #3501: CHAT_STATE_INVALID refuses unusable conversational state before the turn writes or builds a model prompt. CHAT_AUTHORITY_SCOPE_CHANGED refuses a write when the memory encryption flag changed before its lock; obtain fresh context, never automatically resubmit a model call or a turn after an uncertain commit.
chatId String!
userMessage String!
llmModel String #3096 / hrn:node:hadronmemory.com:specs:cor:dmo:150:08: optional client-reported model id, at most 256 UTF-16 code units, no control/format/line-separator characters or unpaired surrogates. Omitted or null fills empty for this call. Used only for prompt text and its immutable record, labelled client-reported; never billing, quotas or authorization. Invalid input refuses BAD_USER_INPUT without echoing it.
aiConfigChoice String #3957 (hrn:node:hadronmemory.com:specs:cor:dmo:050:10): optional AI config choice for this chat, stored with it: `default` or one of the chat App's own config ids from chatAiConfigChoices. Omitted keeps what the chat has. Any other id is refused as a missing config, revealing nothing about it. The choice is stored in a second write, after the user message commits and before any model call: if that write fails, the message is kept, no turn runs, and the chat's previous choice stands. A caller resends the choice, not the message: the message is already stored, so do not send it again; send the choice again with your next message.
processChatResponse ChatResponseResult! Process the LLM's tool response (extract data, transition stage, save assistant message) NOT atomic: the assistant message and message counter commit first, the extracted data is then judged and written in a separate transaction, and the stage advances last. When the authoring gate refuses the extraction (AUTHORING_ATTESTATION_MISSING, AUTHOR_TASK_BROKEN or its other typed reasons) the call errors with that same code and role, and the error's extensions.partialTurn says what the turn did: persisted = [ASSISTANT_MESSAGE, MESSAGE_COUNTER], refused = [{ component: EXTRACTION, code }], notRun = [STAGE_PROGRESSION]. The target data node is untouched. The report names no id, task or revision. Do NOT treat this as a retry-safe call: repeating it may append another assistant message. Success shapes are unchanged.
chatId String!
toolResponse JSON!
saveChatSummary Boolean! Persist a caller-produced chat summary. #1115 — READ THIS BEFORE CALLING. The summary is STORED and nothing reads it back as a summary: no query excludes the messages it covers, and the model-history builder has no summary branch, so the node is replayed as an ordinary user turn ALONGSIDE the messages it summarises. Calling this makes the transcript longer, never shorter. The compression this was built for does not exist yet, and the trigger that used to request it (ChatPromptResult.summarizationNeeded) now always returns null. Kept working so existing callers do not break; re-arming it needs the design in #1115, not a flag.
chatId String!
summary String!
updateChatTitle Boolean! Rename a saved chat with current write access to its host memory. A changed trimmed title is revisioned once (hrn:node:hadronmemory.com:specs:cor:dmo:060:04). A same-title rename writes nothing. Only trusted portal identity mints HUMAN (hrn:node:hadronmemory.com:specs:cor:dmo:060:16); other callers follow the memory's authoring rules and cannot supply authoredWith here. A governed refusal changes neither title, revision nor stamp.
chatId String!
title String!
deleteChat Boolean! Soft-delete a saved chat and all its messages. Requires current write access to its host memory.
chatId String!
updateAgentAIConfig Agent! Update an Agent's AI provider config. Key is encrypted at rest. 036-ai-service-config: upserts the Agent's registry config named 'default'. Prefer createAiServiceConfig/updateAiServiceConfig for new callers. Accepts the entity's ID or URN.
agentId ID!
provider String!
model String!
apiKey String
clearAgentAIConfig Agent! Clear an Agent's AI provider config without returning or decrypting keys. Clearing a user-owned Agent, by its owner or a platform ADMIN/OWNER, removes every named configuration, including disabled configurations. hrn:node:hadronmemory.com:specs:cor:dmo:050:13 An org-owned Agent clear deletes only the configuration named 'default'. Accepts the entity's ID or URN.
agentId ID!
createAiServiceConfig AiServiceConfig! 036-ai-service-config: create a named AI config on an owner entity. apiKey semantics: non-empty = encrypted at rest with a masked preview. Omitted is accepted only where a run may use the server's own credential: a HADRON_SERVER config with no explicit endpoint. Eligible process-credential providers: openai, anthropic, bedrock; every other provider needs its own key. Every ORGANIZATION, APP and AGENT config needs its own key: the platform credential is platform spend (#1390). Any config with an endpoint needs one too, because the SDK would otherwise send the server's credential to a host that didn't issue it (#1389). All of these are refused with AiConfigValidationError. A host that checks no key takes any placeholder. Name is trimmed, must be 1-64 lower-case [a-z0-9_-] starting with a letter or digit, and is unique per owner. provider must be a known provider; params are validated per provider. Auth: platform ADMIN/OWNER for HADRON_SERVER; org ADMIN for ORGANIZATION; the App/Agent's strict owner or owning-org ADMIN for APP/AGENT. A platform role does not bypass a user-owned App/Agent's credential gate. ownerId accepts ID or URN (HADRON_SERVER: ID only).
ownerType AiConfigOwnerType!
ownerId ID!
name String!
provider String!
model String!
apiKey String
params JSON
endpoint String #1373: base URL; https only, no query/fragment/credentials. Omit for the provider default.
apiStyle AiApiStyle #1373: OpenAI-compatible providers only; omit for the provider default.
enabled Boolean
updateAiServiceConfig AiServiceConfig! 036-ai-service-config: update a named AI config. All fields optional. apiKey semantics: omitted = keep the stored key; empty string = clear it (explicit null also clears); non-empty = replace (encrypted, preview recomputed). The RESULTING config is held to createAiServiceConfig's key rule, so clearing the key of a config that needs one is refused. Auth: the same owner-aware credential gate as createAiServiceConfig; managing a user-owned Agent through a platform role alone does not grant access to its stored credential.
id ID!
name String
provider String
model String
apiKey String
params JSON
endpoint String #1373: omitted = unchanged; null or empty string = clear (provider default).
apiStyle AiApiStyle #1373: omitted = unchanged; null = clear (provider default).
enabled Boolean
testAiServiceConfig AiServiceConfigTestResult! #1378: test a SAVED config by id with one small real call, through the same client, endpoint and egress guard a run uses; the stored key never leaves the server. The override argument tests edited values without saving them. Auth: as updateAiServiceConfig; refused under impersonation. Every test that reaches the provider is metered (usage type ai-config-test); NO_API_KEY and KEY_UNREADABLE make no call and record nothing. The call is bounded by a 20s timeout. Rate-limited per caller and config (RATE_LIMITED). #4005: chatProbe (default false) also runs ONE chat probe: the chat turn's own respond tool, sent with the chat turn's tool-choice decision (ChatAiConfigChoice.toolChoice), output capped at 64 tokens, 20s, no retries. Its outcome is the closed AiServiceConfigTestResult.chat status. It is a second, separately metered provider attempt (usage type ai-config-test-chat) under the same one rate-limit unit. Absent or false, the result and the call are exactly what they were.
id ID!
override AiServiceConfigTestOverride
chatProbe Boolean
deleteAiServiceConfig Boolean! 036-ai-service-config: delete a named AI config (hard delete; the resolution walk simply no longer finds it). Auth: admin rights on the owning entity (as aiServiceConfigs).
id ID!
createScope Scope! Spec 049 Phase 2 — create a named scope on exactly one owner. Auth by owner: organization CONTRIBUTOR+; App or Agent ADMIN of the owning org, or the owner of a user-owned one. Name 1–64 [a-z0-9_-], unique per owner among live scopes (SCOPE_NAME_TAKEN), never `global` / `app`.
input CreateScopeInput!
createNodeRoleRule NodeRoleRulePayload! #1325 — add a rule to a memory's config (creating the config on first use). Managers only; anyone else gets MEMORY_NOT_FOUND. A role that already has a rule is refused NODE_ROLE_RULE_EXISTS.
memoryRef ID!
input CreateNodeRoleRuleInput!
updateNodeRoleRule NodeRoleRulePayload! #1325 — change a rule by its id. With expectedRevision, a rule changed since you read it is refused CONFLICT (extensions.currentRevision) and nothing is written; omitted, the last writer wins. A rule you may not manage reads as NOT_FOUND. A LOCKED rule (#1334) is refused with RULE_LOCKED (extensions ruleId, role, sourceTemplateId) for EVERY caller: unlock it first (unlockNodeRoleRule) or re-apply its required template.
ref ID!
input UpdateNodeRoleRuleInput!
expectedRevision Int
deleteNodeRoleRule Boolean! #1325 — delete a rule by its id; expectedRevision as for updateNodeRoleRule. A LOCKED rule (#1334) is refused with RULE_LOCKED for every caller: unlock it first (unlockNodeRoleRule).
ref ID!
expectedRevision Int
unlockNodeRoleRule NodeRoleRulePayload! #1334 — the deliberate step before a rule a required template LOCKED can be edited or deleted (Holger, 2026-09-27: nobody changes a locked rule through an ordinary edit). Needs lock authority: an org ADMIN/OWNER of the memory's org; on a personal/private or org-less memory, its manager. Anyone else who manages the memory gets RULE_LOCKED. Visible: bumps revision and stamps updatedBy. Unlocking an unlocked rule changes nothing. expectedRevision as for updateNodeRoleRule.
ref ID!
expectedRevision Int
applyMemoryConfigTemplate MemoryConfigApplyResult! #1334 — copy a template's rules into ONE memory's config. A one-off copy: later template edits never reach this memory, and re-applying is explicit. Needs MANAGE on the memory (else MemoryNotFound) and on the template, which exists for you only if you manage its owner (else MEMORY_CONFIG_TEMPLATE_NOT_FOUND). The rules are validated as a whole, under a share lock, as createNodeRoleRule validates a new rule's references (NODE_NOT_FOUND for one you cannot read, NOT_A_TASK), and a template rule whose required task was deleted refuses the whole apply (NODE_ROLE_RULE_REF_BROKEN). All-or-nothing per memory. When the memory already has a rule for a role, a non-required template skips it and a required template replaces it. A LOCKED rule is only replaced by a caller with lock authority (see unlockNodeRoleRule); otherwise SKIPPED_LOCKED. Rules written by a required template are locked. expectedTemplateRevision: CONFLICT (with currentRevision) if the template changed since you read it. dryRun: the same report with nothing written.
templateRef ID!
memoryRef ID!
expectedTemplateRevision Int
dryRun Boolean
applyMemoryConfigTemplateToMemories MemoryConfigBulkApplyResult! #1334 bulk apply — applyMemoryConfigTemplate over a list of memories (at most 50; more is BULK_TARGETS_TOO_MANY naming the cap and the count, checked before any work, never a truncation). Targets run one at a time, in input order, each in its OWN transaction exactly as the singular mutation runs one: one target failing never rolls back another, and there is no promise that the whole call saw one version of the template. Each success reports the templateRevision it applied. Refused for the whole call, nothing written: an empty or blank list (BAD_USER_INPUT), an unknown or unmanageable template (MEMORY_CONFIG_TEMPLATE_NOT_FOUND), a stale expectedTemplateRevision (CONFLICT with currentRevision). expectedTemplateRevision is also enforced per target, so a template edited mid-call fails every later target with CONFLICT while earlier ones stay applied. Everything else is per target (see MemoryConfigBulkApplyError). MANAGE on each memory and on the template is asked fresh for every target. A memory you cannot manage reads exactly like one that does not exist, and a memory named twice (by any spelling) is applied once: later positions are DUPLICATE_TARGET with no write, but only for memories you manage. Retrying is safe for FAILED targets only: re-sending a target that succeeded under a required template replaces its rule again. dryRun rolls every target back and is not a preview of a later apply; bind them with expectedTemplateRevision.
templateRef ID!
memoryRefs [ID!]!
expectedTemplateRevision Int
dryRun Boolean
createMemoryConfigTemplate MemoryConfigTemplatePayload! #1325 part (c) — create a template. ownerRef names the organization, user or App; omit it for HADRON_SERVER (platform admins only; refused HADRON_SERVER_NOT_CONFIGURED when this server has no row) and for USER (yourself — you own templates for no one else). A second live template of the same name under the same owner is MEMORY_CONFIG_TEMPLATE_EXISTS.
ownerType MemoryConfigTemplateOwnerType!
ownerRef ID
input CreateMemoryConfigTemplateInput!
updateMemoryConfigTemplate MemoryConfigTemplatePayload! #1325 part (c) — change a template by its id. With expectedRevision, a template changed since you read it is refused CONFLICT (extensions.currentRevision) and nothing is written. A template you may not manage reads as MEMORY_CONFIG_TEMPLATE_NOT_FOUND.
ref ID!
input UpdateMemoryConfigTemplateInput!
expectedRevision Int
deleteMemoryConfigTemplate Boolean! #1325 part (c) — soft-delete a template. Configs it was applied to keep their copies.
ref ID!
expectedRevision Int
updateScope Scope! Spec 049 Phase 2 — update a scope you may write (auth as createScope). memoryRefs replaces the ordered list.
ref ID!
input UpdateScopeInput!
deleteScope Boolean! Spec 049 Phase 2 — soft-delete a scope you may write; its name is free again at once.
ref ID!
createChannel Channel! Spec 049 Phase 4 — create a named Channel with its chat root. The host is any memory class you may write; its audience decides the Channel's (cor:acl:030:01). LOC_OVERLAPS_CHANNEL when the address overlaps an existing Channel's.
input CreateChannelInput!
updateChannel Channel! Spec 049 Phase 4 — rename / re-describe a Channel whose host memory you may write. ref: its id or its address (Channel.chatRootUrn, #1171).
ref ID!
input UpdateChannelInput!
deleteChannel Boolean! Spec 049 Phase 4 — soft-delete a Channel AND its chat root together (the protection holds while either exists). There is no restore: creating a Channel at the same address adopts it and starts clean, so the old transcript does not come back (#1257, #1226). Host memory write access required. An App's default Channel is unlinked from the App. ref: its id or its address (`Channel.chatRootUrn`, #1171).
ref ID!
createRegisterEntry RegisterEntry! Spec 049 Phase 5 — declare that an attendee takes part in a Channel. Owner: an App (org ADMIN / owner of a user-owned App) or an organization (CONTRIBUTOR+). attendeeRef: a Worker or an Agent in the owner's context; omitted = every attendee there. REGISTER_ENTRY_EXISTS when a live row already holds that (owner, Channel, attendee). Intent, never permission.
input CreateRegisterEntryInput!
updateRegisterEntry RegisterEntry! Spec 049 Phase 5 — change a row's role / mentionOnly / description (the owner's gate).
ref ID!
input UpdateRegisterEntryInput!
deleteRegisterEntry Boolean! Spec 049 Phase 5 — soft-delete a row. Each owner removes its own rows; an App may remove its install-created default.
ref ID!
advanceChannelReadState ChannelReadState! Spec 049 Phase 7 — advance an attendee's cursor on a Channel (the relay's write; §8.7 gate: the caller must be the attendee's DRIVER — a user whose live session is bound to that Worker, or the App-key principal of the attendee's App). Monotonic: a lower seq is a no-op that returns the cursor. channelRef: the Channel's id or its address (`Channel.chatRootUrn`, #1171).
attendeeRef ID!
appRef ID
channelRef ID!
seq Int!
markOwnTeamChatRead OwnTeamChatReadState! #3818 / hrn:node:hadronmemory.com:specs:cor:agt:020:03: an acting superseded sessionRef refuses SESSION_SUPERSEDED. #1353: explicitly advance the cursor owned by one exact, caller-owned live Worker session on one readable registered Channel. Shares the MCP mark-read helper; unlike advanceChannelReadState this door requires that session. Monotonic; a seq beyond the captured Channel watermark is refused.
appRef ID!
sessionRef ID!
channelRef ID!
seq Int!
expectedIncarnation Int #2181 — fence the mark to the incarnation you read. It runs in one transaction behind the Channel row lock: a different incarnation is CHANNEL_INCARNATION_CHANGED (never repeat it; read again and pin the new incarnation) and no cursor, check stamp or session resume is applied. A successful fenced response confirms channelIncarnation = the incarnation you pinned and lastSeenSeq >= seq, even when an equal or lower mark left a legacy NULL cursorIncarnation in place. Omitted: the mark is UNFENCED, as before.
confirmTeamAttentionSwitchover TeamAttentionSwitchoverResult! Explicitly confirm a previously previewed #1353 switchover. The proof is actor/App/scope-bound; any live-Worker, register or cursor drift rejects the whole transaction. It advances only through the heads captured by the preview, so messages arriving afterward remain unread.
appRef ID!
proof String!
createRevision RevisionResult! Snapshot an Agent's system memory as a new revision. Accepts the entity's ID or URN.
agentId ID!
description String
publishRevision RevisionResult! Publish a revision and pin the Agent to it. Accepts the entity's ID or URN.
agentId ID!
revisionLoc String!
versionLabel String
restoreRevision RevisionResult! Restore an Agent's system memory from a revision (auto-saves first). Accepts the entity's ID or URN.
agentId ID!
revisionLoc String!
acquireEditorLock EditorLockResult! Acquire (or renew) the editor lock for an Agent's system memory. Accepts the entity's ID or URN.
agentId ID!
releaseEditorLock Boolean! Release the editor lock for an Agent's system memory. Accepts the entity's ID or URN.
agentId ID!
joinWaitingList Boolean!
email String!
requestedFeatures String
sendContactMessage Boolean!
name String!
email String!
message String!
createApp App! Create an App and install its initial Agent. With orgRef, the App is owned by that Organization and requires org ADMIN; without orgRef, it is owned by the authenticated User and remains owner-only. An org-owned install auto-provisions an AgentOrgGrant only for its own Agent. A cross-org install requires an existing active grant; subscribe to a PUBLIC Agent through createAgentOrgGrant before creating the App. It adds the caller as an AppMember with role 'owner' only when that role is present in the Agent's installationPolicy and the caller is a User. Required AgentImports cascade automatically for org-owned Apps; optional imports cascade only when their id appears in installOptional. Personal Apps reject dependency cascades in v1. Selected dependencies must also be licensed before any App is created. The server enforces this even when a caller bypasses the portal. Accepts the entity's ID or URN.
orgRef ID Provide to create an ORG-owned App (requires org ADMIN). OMIT to create a USER-OWNED App owned by the caller — rooted on the caller's bare handle (hrn:app:<handle>:<slug>, grammar v2 — no @ sigil), owner-only. Accepts the org's ID or URN.
agentRef ID! The initial Agent installed into this new App. Required as of 009-install-agent-flow: every new App starts with an installed Agent. For an org-owned App, the server auto-provisions a grant only for an Agent owned by that org; any cross-org Agent needs an existing active AgentOrgGrant. A personal App accepts only a PUBLIC Agent or one owned by the caller, and licenses a foreign PUBLIC Agent through the owner's AgentSubscription.
name String!
urn String
appType AppType
role AppMembershipRole
description String
agentTools [String!]
aiProvider String
aiModel String
aiApiKey String 036 legacy shim over the App's 'default' AI config; held to createAiServiceConfig's key rule (#1389).
expiresAt String
surfaces [String!]
trainingMode Boolean
installOptional [ID!] 008-agent-installation: optional dep Agent ids to cascade-install. Required imports of the parent Agent always cascade; optional imports install only when their id appears here. Pass [] (or omit) to skip all optional deps. v1 accepts ID or URN.
createUserPermission CreateUserPermission
identifyUserMethod IdentifyUserMethod
sessionTimeoutSeconds Int
anonymousTtlDays Int
policy JSON App-layer action-policy link (hrn:node:hadronmemory.com:specs:cor:acl:040:02, #510). Null or omitted = no restriction.
updateApp App! Update an App. Accepts the entity's ID or URN. An uninstalled App is kept read-only (hrn:node:hadronmemory.com:specs:cor:dmo:050:21): this refuses it with APP_UNINSTALLED, for every field, after the access gate, writing nothing.
ref ID!
name String
urn String
appType AppType
role AppMembershipRole
description String
agentTools [String!]
aiProvider String
aiModel String
aiApiKey String 036 legacy shim over the App's 'default' AI config; held to createAiServiceConfig's key rule (#1389).
expiresAt String
surfaces [String!]
trainingMode Boolean
createUserPermission CreateUserPermission
identifyUserMethod IdentifyUserMethod
sessionTimeoutSeconds Int
sessionDormancyDays Int Ruling DY-5: the dormancy threshold in days (a positive integer). See App.sessionDormancyDays.
agentSessionsExpire Boolean Ruling DY-3: see App.agentSessionsExpire.
anonymousTtlDays Int
policy JSON #3423: the App-layer action-policy link (hrn:node:hadronmemory.com:specs:cor:acl:040:02, #510), shaped { allow: [String!] }. Explicit null clears; omitted preserves. Same gate as every other updateApp field.
deleteApp Boolean! Soft-delete an App. Accepts the entity's ID or URN.
ref ID!
uninstallApp Boolean! #3774 — Uninstall an App: it is kept, read-only (every write through it is refused, usually APP_UNINSTALLED), and its handle is free for a new App. Ends every open dark-worker episode of the App's workers at the uninstall time, in the same transaction (hrn:node:hadronmemory.com:specs:cor:dmo:050:21, Holger R1-R3, 2026-11-09). Whoever may deleteApp may call this (the same gate); anyone else, and an App that does not exist, gets one identical refusal. A repeat on an uninstalled App changes nothing. A deleted App is refused (APP_DELETED). Accepts the ID, or a URN: it names the installed App holding it, else the one uninstalled App with it.
ref ID!
reinstallApp Boolean! #3774 — Reinstall an uninstalled App: the SAME App (id, keys, members, memories) is installed again; no row is created (hrn:node:hadronmemory.com:specs:cor:dmo:050:21, R2). Same gate as uninstallApp. Refused APP_URN_IN_USE while another installed App holds the handle, and APP_DELETED for a deleted App (there is no undelete). A repeat on an installed App changes nothing. Accepts the ID, or a URN: it names the installed App holding it (so a repeat by URN is a no-op), else the one uninstalled App with it (two or more: name one by id). The refusal's extensions carry appId and urn. A worker that is still dark opens a NEW episode on the next sweep.
ref ID!
installAgentIntoApp InstallAgentIntoAppPayload! Install an Agent into an App (023-app-shape US1). Creates an AppAgent row joining the two. An App can have multiple Agents installed; one credential addresses all of them. This is the ONE operation that attaches an EXISTING Agent to an EXISTING App — distinct from createApp (which makes a NEW App from an Agent). It is therefore also the re-attach that cor:dmo:050:03 promises: detaching an Agent retains the memories accumulated under that App-and-Agent pairing as orphans, and installing the Agent again is what makes them reachable. Under cor:agt:020:01 the AppAgent join is a team's install ROSTER (which agents are available); the App's STAFF are its Workers, cast from installed agents with castWorker. Worker rows survive uninstall (cor:dmo:050:11) — uninstalling severs future casting, not history. Rejects with code DUPLICATE_APP_AGENT when the Agent is already installed in the App. Authorization: the owner of a user-owned App, or an org member with CONTRIBUTOR+ on an org-owned App's org (platform admins included). NOT plain AppMembers: installing an existing Agent is itself a read grant on that Agent's design — its system memory becomes readable from every App context, and the returned Agent carries its definition — so this gate stays at the level that can already read the org's Agents. Accepts the entity's ID or URN for both appRef and agentRef. Optional trainingMode flag updates the per-App training flag (applies to every installed Agent — training mode is per-App, not per-Agent, per spec 023 FR-001).
appRef ID!
agentRef ID!
trainingMode Boolean
castWorker Worker! #974 — cast a Worker (cor:dmo:050:11, cor:agt:020:01/:02): the named casting of an agent ALREADY INSTALLED in the App, superseding createTeamPersona's minting semantics (nothing is minted — the agent carries the persona dressing; the Worker is the local named identity). Casting is opt-in, never requires a Team Agent (an explicit name skips the register entirely), and multiple castings of one agent per App are legal (Iris and Henry, both backend-engineer). Agent resolution: agentRef when given (must be installed here — WORKER_AGENT_NOT_INSTALLED); otherwise role picks the single installed agent whose personaRole matches (zero / several candidates: WORKER_AGENT_NOT_FOUND / WORKER_AGENT_AMBIGUOUS, never a guess). The casting's role is the agent's personaRole and cannot be overridden (hrn:node:hadronmemory.com:specs:cor:dmo:050:11, R222): beside an agentRef, a role that is not that agent's refuses WORKER_ROLE_OVERRIDE_REFUSED. The casting check (#2458) is shared with changeWorkerAgent: the App's holder must be licensed for the agent (AGENT_ORG_GRANT_INACTIVE / AGENT_ORG_GRANT_REQUIRED; a missing same-organization grant is no refusal and a revoked one is) and for every Agent its served boot prompt includes from (BOOT_PROMPT_GRANT_REQUIRED / BOOT_PROMPT_INCLUDE_UNAVAILABLE). The name (cor:agt:020:02) is REQUIRED since #1050 — one attempt, and WORKER_NAME_TAKEN is the answer. There is no register to fall back to: a name is permanent within the App, so it is chosen and never derived, and a nameless cast refuses WORKER_NAME_REQUIRED rather than minting a permanent identifier nobody picked. The workers_app_name_uniq constraint IS the arbiter. Names are unique per App, case-insensitively, FOREVER (two Apps may each have an Iris; retirement and uninstall never free a name). Names whose mention token is a broadcast word are refused WORKER_NAME_RESERVED; choose a name whose token does not broadcast. #1677: NFKC-normalized Unicode 16 UTS #39 skeletons (original-case and caseless) must also be distinct within the App, including retired workers. A collision refuses WORKER_NAME_CONFUSABLE and names the existing worker; the chosen display spelling is preserved. Existing workers are not renamed or invalidated. A worker-scoped working memory is provisioned in the App's container (Worker.memoryId; best-effort — a failed provision leaves it null for lazy provisioning). Authorization: an org member with CONTRIBUTOR+ on the App's org, an AppMember of the App whose role is not 'reader', or the owner of a user-owned App. Pure App-key principals are denied. Error codes (extensions.code): WORKER_NAME_TAKEN, WORKER_NAME_CONFUSABLE, WORKER_NAME_REQUIRED, WORKER_NAME_RESERVED, WORKER_NAME_RESERVED_TEAM_PREFIX (a mention token starting team., refused only while TEAM_TAGS_ENABLED), WORKER_AGENT_NOT_INSTALLED, WORKER_AGENT_NOT_FOUND, WORKER_AGENT_AMBIGUOUS, APP_UNINSTALLED. #1050 also removed WORKER_ROLE_NOT_FOUND from this mutation: it fired only because a nameless cast had to find a roles:<role> node to read a register. An unrecognized role now resolves no agent (WORKER_AGENT_NOT_FOUND) or, with an explicit agentRef, is simply the casting's label. #1050: the TEAM_AGENT_* and SESSION_EXPIRED refusals are gone from this mutation. They were reachable only because a nameless cast had to locate a Team Agent and read its (possibly encrypted) system memory to find a register. Casting now touches no system memory at all, so teamAgentRef is gone too rather than left accepted-and-ignored. Accepts the entity's ID or URN for appRef and agentRef.
appRef ID!
agentRef ID
role String
name String #1050: a name is now mandatory in EFFECT but stays nullable in the schema, refused at the resolver with the typed WORKER_NAME_REQUIRED. A non-null String would report the same mistake as a bare validation error, losing the reason a name cannot be derived — and it would split this surface from the MCP tool, which calls the resolver directly and would keep the typed refusal. One rule, one message, both paths.
reportsTo ID Worker reference to report to. Requires worker-staffing access and App management. Supply either reportsTo or noTeam: true, never both. Null or a blank reference is invalid.
noTeam Boolean Set to true to record that the worker has no reporting head; do not supply reportsTo as well. Null or false is invalid. Omitting both arguments records no choice (UNSET) when omission is allowed; otherwise the request is refused with WORKER_TEAM_CHOICE_REQUIRED.
instruction ActInstructionInput #3308: a held worker needs this validated instruction or its own live workers.staff grant; host-launched sessions are always headless. The holder still needs staffing rights. Instruction claims are recorded, including previews/no-ops (hrn:node:hadronmemory.com:specs:cor:dmo:050:12, hrn:node:hadronmemory.com:specs:cor:agt:080:24).
retireWorker Worker! #974 — retire a Worker (cor:agt:020:02): end the casting while reserving its name FOREVER. A retired worker stops authoring team chat at once (the worker-App pin checks retirement at post time), takes no new work records, and refuses new session bindings; the row and its name reservation survive. Idempotent — retiring an already-retired worker returns it unchanged; an instructed no-op records its claim only. Same instruction/grant authorization as castWorker. workerRef is the worker's id or its URN (#991). Retiring clears the worker's own reportsTo (#1726); workers that report to it keep theirs and read reportsToRetired.
workerRef ID!
instruction ActInstructionInput
setWorkerReportsTo Worker! #1726 — set, hand over or clear (reportsTo: null) who a worker reports to: a non-retired worker of the same App, never itself, never a cycle (WORKER_REPORTS_TO_SELF / _OTHER_APP / _RETIRED / _CYCLE; WORKER_RETIRED for a retired worker). Allowed for whoever manages the App, and for the worker it reports to now (handing over or clearing is its agreement). A worker that reports to nobody may also be claimed by a worker for itself when one person holds both, or placed under any worker by its own holder (interim, pending a ruling). WORKER_REPORTS_TO_FORBIDDEN otherwise. A worker acts through its bound session, with a person behind the request. Each change is a `worker.reports-to` team event. An explicit clear records NO_TEAM, including a previously UNSET line; repeating the recorded choice changes nothing.
workerRef ID!
reportsTo ID
releaseWorker ReleaseWorkerPayload! #1050 — release a HELD name, so somebody else can hold it. A name is held by a person until released; nothing else frees one, which is what makes availability a fact rather than a judgement about whether an idle driver is really gone. Two principals may call this, and they are different acts: the HOLDER, releasing their own name and owing nobody notice; or an App/org ADMIN, force-releasing somebody else's — the path that exists so a departed colleague's names are not held forever. An admin force-release POSTS TO THE TEAM CHAT, naming who released what and from whom, because the incident this model answers is exactly the one where notice was owed and there was no way to give it. Best-effort: an unreachable chat never blocks the release. Releasing does NOT retire the worker, free the name for a different casting, or touch its history — the name stays permanently allocated to this casting, and the handoff sequence and worklog travel with the worker to whoever holds it next. Idempotent: releasing an unheld worker returns it unchanged. #1073 — OPTIONAL PRECONDITION. The two release paths are different acts: the holder's own release notifies nobody, an admin force-release announces itself in the team chat. A client that wants to tell its user which one it is about to perform can only classify from a pre-read, and the hold can change in between — so the act performed differs from the act described, and a hold taken in that interval is force-released silently. State what you expect and the server refuses instead. Pass expectedHolderUserId to assert a specific holder, or expectUnheld: true to assert there is none; a mismatch refuses WORKER_HOLD_STALE carrying the holder actually found. Passing neither keeps the unconditional behaviour, so this is additive. Passing both is BAD_USER_INPUT. Two arguments rather than one nullable id on purpose: distinguishing "expect nobody" from "no expectation" through a nullable argument would rest on KEY PRESENCE, and any layer that forwards the argument unconditionally sends undefined — present, and read as an assertion nobody made. That is a live hazard in this codebase, so a safety precondition does not lean on it.
workerRef ID!
expectedHolderUserId ID Assert the name is held by exactly this user. Mismatch refuses WORKER_HOLD_STALE.
expectUnheld Boolean Assert the name is held by nobody. Mismatch refuses WORKER_HOLD_STALE.
updateWorker Worker! #1010 — amend a casting's signature and trailer after the fact (hrn:node:hadronmemory.com:specs:cor:agt:040:04). #2712 removed the per-worker prompt override: a worker's own boot prompt is its compiled boot source (hrn:node:hadronmemory.com:specs:cor:agt:040:06), changed by compile and approve. Signature/trailer edits require an App manager acting as themselves, or a worker held by that manager carrying an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12). A host-launched or uninstructed worker is FORBIDDEN. An instructed act records the worker, holder and instruction reference in one team event; a person records no instruction. Omitted preserves, null refuses, whitespace-only becomes empty text; other text is raw, max 2000 characters, no NUL. A mixed update is atomic. These values reach the next compose/bind via S4. A retired worker refuses WORKER_RETIRED. `name` is permanent by law (hrn:node:hadronmemory.com:specs:cor:agt:020:02). The agent (and with it the role) is changed by changeWorkerAgent, not here. A call naming neither field changes nothing and keeps castWorker staffing authorization. workerRef is the worker's id or URN (#991).
workerRef ID!
signature String
trailer String
instruction ActInstructionInput
changeWorkerAgent Worker! #2458 (hrn:node:hadronmemory.com:specs:cor:dmo:050:11, R222): change the agent a worker casts. The role follows the agent and is never typed in. Name, slug, URN, signature, trailer, reporting line and every past record stay; past sessions keep the agent and role they ran under (Session.agentId, Session.role). Who: whoever manages the App, as themselves, or their held worker with an instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12). A host-launched or uninstructed worker, an App key, an impersonation or a run is FORBIDDEN. The casting event records an admitted worker's instruction. To what: the same checks as castWorker (WORKER_AGENT_NOT_INSTALLED, AGENT_ORG_GRANT_INACTIVE / _REQUIRED, BOOT_PROMPT_GRANT_REQUIRED / BOOT_PROMPT_INCLUDE_UNAVAILABLE, APP_UNINSTALLED). Also WORKER_RETIRED, WORKER_AGENT_UNCHANGED (it already casts that agent), WORKER_AGENT_HAS_NO_ROLE (the agent has no personaRole to change to) and WORKER_CASTING_STALE (a concurrent change; read again). A refused change changes nothing. A complete change, in one transaction: the worker's own boot-prompt pointer is cleared (it named the old agent's compiled prompt), the old agent's generated tickers end and the new agent's are made, and one `worker.casting` team event records who and the old and new agent and role. It takes effect at the worker's next bind: an open session finishes under the agent and role it was bound with. workerRef and agentRef are ids or URNs.
workerRef ID!
agentRef ID!
instruction ActInstructionInput
setAgentBootPrompt Agent! #2045 (S8) — set or clear an Agent's boot-prompt pointer. nodeRef (a node id or a fully-qualified node URN) must name a COMPILED boot prompt in this Agent's own system memory; approval is not required here (it is checked when the prompt is served). nodeRef is REQUIRED: an explicit null clears, and an omitted one is refused with BAD_USER_INPUT. Only the Agent's manager, acting as themselves (R23): a request bound to a worker session, the manager's own included, is refused BOOT_PROMPT_POINTER_SESSION_REFUSED; a non-manager, an App key, an impersonation or a run is FORBIDDEN. The gate runs before the target is looked at, so a refused caller learns nothing about it. Then: BOOT_PROMPT_POINTER_NOT_FOUND (missing, deleted or unreadable, alike), _NOT_COMPILED, _WRONG_ROLE, _WRONG_MEMORY. No MCP twin (R24).
agentRef String!
nodeRef String
setAppAgentBootPrompt AppAgent! #2045 — set or clear an installed Agent's boot-prompt pointer for one App (AppAgent.bootPromptRef). The node must be compiled and sit in that App's install memory for that Agent. Only the App's manager, as themselves; otherwise as setAgentBootPrompt.
appRef String!
agentRef String!
nodeRef String
setOrgBootPromptSigning OrgBootPromptSigning! #2973 PR2 / hrn:node:hadronmemory.com:specs:cor:agt:040:09: switch an organisation's boot-prompt signing on or off. The audience is orgBootPromptSigning's (current ADMIN or OWNER, as themselves; every other shape is FORBIDDEN, the same for an organisation that does not exist), re-checked inside the transaction. No passkey or step-up either way. Off needs nothing and is idempotent. On requires the previewToken of a preview fetched with orgBootPromptSigningPreview by THIS caller for THIS organisation in the last ten minutes: the server locks the organisation, recomputes the whole preview and refuses BOOT_PROMPT_SIGNING_PREVIEW_STALE, changing nothing, when the token is missing, forged, another organisation's or caller's, expired, future-dated, or describes a preview that has since changed. That refusal comes only after the audience check. On when already on, with a valid token, succeeds and changes nothing. Turning the switch on does not turn on the deployment's signing: read enforced.
org ID!
required Boolean!
previewToken String
setWorkerBootPrompt Worker! #2045 — set or clear a worker's boot-prompt pointer (for customised workers). The node must be compiled and sit in the worker's App's install memory for the worker's Agent. Only the App's manager, as themselves; otherwise as setAgentBootPrompt. workerRef is the worker's id or URN.
workerRef ID!
nodeRef String
compileAgentBootPrompt CompiledBootPrompt! #2046 (S9-4, hrn:node:hadronmemory.com:specs:cor:agt:040:12) — compile an Agent's boot prompt from its source ('boot:source') in the Agent's system memory into the compiled node 'boot:compiled' there, as a NEW unapproved revision (every compile writes one, even when the text is unchanged), with its provenance and a derived 'compiled-from' edge to the source. Sets 'Agent.bootPromptRef' unless 'setPointer: false'. Never approves or signs ('approvalIssued' is always false). Whoever manages the Agent, as themselves: a request bound to a worker session, a non-manager, an App key, an impersonation, a run, and a target that does not exist are alike refused BOOT_PROMPT_COMPILE_NOT_PERMITTED. Only then: BOOT_PROMPT_TARGET_RETIRED, BOOT_PROMPT_NO_SOURCE, BOOT_PROMPT_SOURCE_INVALID, the include refusals (BOOT_PROMPT_INCLUDE_*, _GRANT_REQUIRED, _COMPILE_LIMIT_EXCEEDED, with the tag's 'position'), and CONFLICT when the compile could not settle inside its 30-second budget (retry). A refusal changes nothing. No MCP twin.
agentRef String!
setPointer Boolean
compileAppAgentBootPrompt CompiledBootPrompt! #2046 — compile an installed Agent's boot prompt for one App into 'boot:compiled' in the App's install memory (the App's own 'boot:source' if it has a live one, else the Agent's, with the App's replacing nodes). Always sets 'AppAgent.bootPromptRef'. Whoever manages the App; otherwise as compileAgentBootPrompt.
appRef String!
agentRef String!
compileWorkerBootPrompt CompiledBootPrompt! #2046 — compile a customised worker's boot prompt from 'boot:workers:<workerId>:source' into 'boot:workers:<workerId>:compiled' in the App's install memory. Sets the worker's pointer unless 'setPointer: false'. Whoever manages the worker's App; otherwise as compileAgentBootPrompt. workerRef is the worker's id or URN.
workerRef ID!
setPointer Boolean
deleteWorker Boolean! #1162 — hard-delete a never-referenced miscast only. hrn:node:hadronmemory.com:specs:cor:dmo:050:11 Empty normally ended and released stints are repairable; persisted attribution, including tombstones/history, refuses WORKER_IN_USE. The requester must explicitly verify no signed commit, trailer, PR, comment, review or published artifact attributes work to this Worker. Database counts cannot prove external absence: known or uncertain external history means retire instead. Omitted or false confirmation refuses WORKER_EXTERNAL_ATTRIBUTION_UNCONFIRMED. No external crawl. Also removes empty ended stints and the empty working memory. Same staffing authorization as castWorker: instruction or own workers.staff grant for a worker session.
workerRef ID!
confirmNoExternalAttribution Boolean
instruction ActInstructionInput
createTeamRole TeamRole! #960 — mint a roles:<role> definition in the Team Agent's system memory. Owns the spec knowledge a hand-authoring caller had to carry: the loc is roles:<role> (single atom). Refuses an existing role (TEAM_ROLE_EXISTS — updateTeamRole is the edit path). Authorization is the Team Agent's definition-edit gate: whoever may write the agent's system memory through the generic node surface may write roles — the write delegates to that same seam (encryption, revision snapshot, git mirror included). #1024 deliberately does NOT take `repos` here — set it with updateTeamRole. A create that also wrote data could not be made atomic: the write resurrects a tombstone through an unguarded upsert branch, and splitting it into create-then-guarded-update introduced a partial failure between the halves (the role lands, the repo write refuses). Two explicit calls put that seam where the caller can see and retry it, instead of hiding a non-atomic pair inside one mutation. #1050: a role definition no longer carries a NAME REGISTER. There is no names / nameRange / nameConvention / allowOutOfRange, and no register invariants to run, because names are not allocated — a cast supplies its own and workers_app_name_uniq is the sole arbiter. Any data.names left on an existing node is historical and is neither read nor rewritten.
appRef ID!
teamAgentRef ID
role String!
description String
updateTeamRole TeamRole! #960 — edit a roles:<role> definition. Omitted fields preserve. Unknown role: WORKER_ROLE_NOT_FOUND. Same authorization as createTeamRole. #1024: `repos` sets the role's repo affinity. Omitted PRESERVES; an empty array CLEARS; explicit `null` is treated as OMITTED, not as a clear — worth stating because a client whose variables default to null would otherwise have to guess, and the two readings differ (preserve vs wipe). Pass `[]` to clear deliberately. It is merged into the node's `data` rather than replacing it, and the write is guarded on the row's revision — a concurrent generic node write (updateNode, hadron_update_node_data) refuses TEAM_ROLE_DATA_CONFLICT rather than silently reverting, since those surfaces do not take this one's lock. Retry after re-reading. A description-only edit carries no data and takes no guard. #1050: with the register gone this otherwise edits the description alone, so the #987 expectedNames compare-and-swap is gone too — it existed solely to stop two concurrent wholesale register writes silently dropping each other's newly added FREE names, a hazard that cannot arise when the write owns no list. That closes #1028 (the client-side register CAS arithmetic) outright rather than by implementing it.
appRef ID!
teamAgentRef ID
role String!
description String
repos [String!]
deleteTeamRole DeleteTeamRolePayload! #1002 — retire a roles:<role> definition. Soft-deletes the role node and any sub-nodes under it (roles:<role>:notes is content OF the role), so the subtree is recoverable. Unknown role: WORKER_ROLE_NOT_FOUND. Same authorization as createTeamRole. #1050: unconditional. The minted-name check, TEAM_ROLE_IN_USE, transferTo's one-step supersede, the post-delete recheck and the restore compensation all existed to protect the REGISTER as a ledger of which names had been allocated to this role; with no register there is no ledger to protect and no second write to compensate for. What that machinery protected is unchanged, and was never the register's doing: a Worker's name is permanent per App (cor:agt:020:02, enforced by workers_app_name_uniq irrespective of any role), so deleting a role can no more free a taken name than it could before. Superseding a role is now create-the-successor then delete-the-old; the names were never the thing being moved.
appRef ID!
teamAgentRef ID
role String!
createTeamChatMessage TeamChatMessage! Post a message into a team App's chat (#939) as a platform operation. The team chat is ONE well-known chat per team App, at loc chats:team in the Team Agent's shared app-class memory, bootstrapped on first post. The message is written through the atomic chat-message allocator (#919), so racing posts get distinct consecutive seqs. Author derivation (#974): with sessionRef, the message is authored by that session's bound non-retired Worker. The session must be writable by the caller and live (or eligible for the shared lapsed-session resume). Its Worker belongs to this App, or its on-behalf-of user may write the Channel's host memory (item J below). The envelope records the driving sessionId; without it, the author is the calling human. Mentions ('@worker-name' / '@handle'; a multi-word name is mentioned by its slug, e.g. '@mary-jane') are extracted server-side at write time into the envelope. replyToSeq wires a replies-to edge to the cited message. body is capped at 65536 characters. Authorization: an AppMember of the App (any role — every member of the host is a participant per cor:acl:030:01), an org member with CONTRIBUTOR+ on the App's org, or the owner of a user-owned App. Pure App-key principals cannot post. Spec 049 Phase 8 (item J): the worker-App pin became the host-memory write check. A session's Worker authors here when its App is this one, OR when the session's on-behalf-of user may write the Channel's host memory — a cross-App post records authorAppId. A pure App-key session is admitted only on the same-App branch. SESSION_NOT_IN_APP and SESSION_WORKER_NOT_IN_APP are retired; CHANNEL_HOST_NOT_WRITABLE is the successor code. A worker's post that repeats its own earlier message is refused: the same worker (across its sessions), the same Channel, exactly the same body and the same reply target (or none on both sides), within the preceding ten minutes, with TEAM_CHAT_DUPLICATE. The earlier message was posted, so do not retry: the text and the typed fields (earlierSeq, channelId) name it. Nothing is stored. A post made as the human (no session) is not judged. Error codes (extensions.code): TEAM_CHAT_BODY_TOO_LARGE, TEAM_CHAT_DUPLICATE, TEAM_CHAT_REPLY_NOT_FOUND, SESSION_NOT_FOUND, SESSION_ENDED, SESSION_NOT_LIVE (dormant or ineligible for lapsed-session resume), SESSION_NOT_WORKER_BOUND, CHANNEL_HOST_NOT_WRITABLE, WORKER_RETIRED, SESSION_EXPIRED (encrypted team memory without an active session key), TEAM_AGENT_NOT_FOUND / TEAM_AGENT_AMBIGUOUS (first-post bootstrap could not locate the Team Agent), APP_UNINSTALLED, FORBIDDEN (an authenticated caller who is not a participant), UNAUTHENTICATED (no principal at all: no token, an expired or unverifiable one; checked before the App is resolved, so it answers identically whether or not the App exists). #3818: an acting superseded sessionRef refuses SESSION_SUPERSEDED; current open sessionId/startedAt are included only under hrn:node:hadronmemory.com:specs:cor:agt:020:03 session read access. appRef accepts the entity's ID or URN; sessionRef is the session id.
appRef ID!
body String!
replyToSeq Int
sessionRef ID
createChannelMessage TeamChatMessage! Spec 049 Phase 8 — post into ANY Channel by ref (its id, or its address — `Channel.chatRootUrn`, #1171): the createTeamChatMessage contract (author derivation, mentions, replyToSeq, the body cap, item J) addressed by Channel. While TEAM_TAGS_ENABLED (default off) a post also carries the sender's team tags, and an invalid `@team..all` target refuses the whole post TEAM_CHAT_TEAM_HEAD_INVALID. createTeamChatMessage is the appRef → App.defaultChannel convenience over this — one gate, two entry points. A Channel you may not read is CHANNEL_NOT_FOUND; one you may read but not post into is FORBIDDEN. A worker's identical repeat within ten minutes is refused TEAM_CHAT_DUPLICATE, exactly as createTeamChatMessage documents.
channelRef ID!
body String!
replyToSeq Int
sessionRef ID
recordTeamWork TeamWorkItem! Record an externally visible work milestone into the team App's worklog (#947) — the append-only, authoritative PR-session join (spec cor:agt:020:03). The session must be writable by the caller and a session OF this App (SessionInput.appRef, #944); an ENDED session is accepted — late attribution (a merge lands after the session ends) is the point. ref accepts URL and short spellings and is stored in ONE canonical form (github: owner/repo#N, owner/repo@sha, owner/repo:branch, owner/repo); a bare number is refused — the server never infers a repo. kind must be one of pr, issue, commit, branch, repo; action is a free lowercased verb (opened, merged, claimed, reviewed, closed, pushed, ...). kind: pr also denormalizes the latest-wins Session.prNumber display convenience. detail is an optional JSON bag of display extras (title, URL) — stored, never filtered on. Records are append-only: correct a wrong record by recording a newer one. Authorization: an AppMember of the App (any role), an org member with CONTRIBUTOR+ on the App's org, or the owner of a user-owned App. A pure App-key principal may NOT record (read-only on the worklog). A worker-bound session records under its Worker's name (#974, cor:agt:020:05) — the worker must belong to THIS App and not be retired (SESSION_WORKER_NOT_IN_APP / WORKER_RETIRED — a retired or foreign worker refuses rather than reshaping the attribution); an unbound session records under the attributed user's handle. Typed refusals: WORK_REF_INVALID, SESSION_NOT_FOUND, SESSION_NOT_IN_APP, SESSION_WORKER_NOT_IN_APP, WORKER_RETIRED, TEAM_AGENT_NOT_FOUND / TEAM_AGENT_AMBIGUOUS (first-write bootstrap could not locate the Team Agent), APP_UNINSTALLED, FORBIDDEN, BAD_USER_INPUT. appRef accepts the entity's ID or URN; sessionRef is the session id.
appRef ID!
sessionRef ID!
tool String!
kind String!
ref String!
action String!
detail JSON
model String Optional explicit model report (#1398). Takes precedence over the session's model; a model switch or a late record should pass the model that actually did the work. Empty string is refused — pass nothing to fall back to the session's model.
updateTeamCollections TeamCollectionsPayload! (Re)declare the server-owned team collections on the team App's shared memory, converging a drifted declaration to the canonical definition (hadron-cli#401). Idempotent: 'changed' is false when the declaration already matched. Why this exists as its own operation. recordTeamWork declares the worklog collection on first write, but deliberately leaves an ALREADY-declared one untouched — a deployment that tightened it governs that surface too, which is the point of schema governance. A declaration is not always a deployment decision though: 'hadron team init' shipped a client-side copy of this schema that has since drifted from the server's (its kind enum predates the 'repo' kind), so on a CLI-bootstrapped memory a recordTeamWork(kind: 'repo') is refused by a rule nobody chose. Overriding silently would break real governance; this operation makes convergence an explicit act instead. Only the server-owned collections are rewritten — every other collection on the memory is preserved. Authorization: owner or org ADMIN on the memory, the same bar updateMemory applies to a schema edit. Team participation is deliberately NOT enough: it lets you record work, not redefine what a record is. Typed refusals: APP_UNINSTALLED, UNAUTHENTICATED, TEAM_AGENT_NOT_FOUND / TEAM_AGENT_AMBIGUOUS (when the App's shared memory must still be bootstrapped). Accepts the entity's ID or URN.
appRef ID!
uninstallAgentFromApp UninstallAgentFromAppPayload! Uninstall an Agent from an App. Deletes the AppAgent row. The Agent's per-(App, Agent, *) memories are NOT cascade-deleted (spec 023 FR-005); they persist as orphans and become reachable again if the same Agent is later reinstalled. Idempotent — succeeds whether or not the AppAgent row exists. Accepts the entity's ID or URN.
appRef ID!
agentRef ID!
addAgentToApp ⚠️ App! DEPRECATED: use installAgentIntoApp. Carried for source-compat with pre-023 portal callers. Accepts the entity's ID or URN.

⚠️ DEPRECATED

Use installAgentIntoApp (spec 023-app-shape US1). Returns Payload type with the AppAgent row.
appRef ID!
agentRef ID!
trainingMode Boolean
removeAgentFromApp ⚠️ App! DEPRECATED: use uninstallAgentFromApp. Carried for source-compat with pre-023 portal callers. Accepts the entity's ID or URN.

⚠️ DEPRECATED

Use uninstallAgentFromApp (spec 023-app-shape US1).
appRef ID!
agentRef ID!
ensureAppMember AppMember! Idempotent UPSERT of an AppMember row. Per spec 008-agent-installation FR-004 / FR-016. The role MUST be a value present in the parent Agent's installationPolicy.memberRoles. Creating a new member is rejected if the App's current member count meets or exceeds the Agent's installationPolicy.maxMembers. Updating an existing member's role does NOT trigger the maxMembers check. The primary installed Agent (the oldest AppAgent) supplies this policy; no installed Agent refuses OrphanAppError. Only an App member manager may call this: the user-owner, an owner-role AppMember, or owning-org ADMIN (including platform admins for org-owned Apps). The manager gate runs before target-user lookup. Accepts the entity's ID or URN.
appRef String #764 — the App as an id / URN. Supply this OR appId.
appId ID

⚠️ DEPRECATED

Use appRef (accepts id / URN).
userRef String #764 — the user as an id / email / handle / hrn:user:<handle> URN. Supply this OR userId.
userId ID

⚠️ DEPRECATED

Use userRef (accepts id / email / handle / URN).
role String!
instruction ActInstructionInput #3308: worker sessions need a validated instruction or their own live app.members grant, including self-leave; the holder still needs the original manager/self right. Refusal precedes target-user resolution. Instructed no-ops record a claim only (hrn:node:hadronmemory.com:specs:cor:dmo:050:12, hrn:node:hadronmemory.com:specs:cor:agt:080:24).
removeAppMember Boolean! Delete an AppMember row. Idempotent (no-op when the row doesn't exist). Personal-class memory at (appId, userId) is retained as an orphan per FR-015 — re-attaches automatically if the user later rejoins the same App. Accepts the entity's ID or URN.
appRef String #764 — the App as an id / URN. Supply this OR appId.
appId ID

⚠️ DEPRECATED

Use appRef (accepts id / URN).
userRef String #764 — the user as an id / email / handle / hrn:user:<handle> URN. Supply this OR userId.
userId ID

⚠️ DEPRECATED

Use userRef (accepts id / email / handle / URN).
instruction ActInstructionInput #3308: worker sessions need a validated instruction or their own live app.members grant, including self-leave; the holder still needs the original manager/self right. Refusal precedes target-user resolution. Instructed no-ops record a claim only (hrn:node:hadronmemory.com:specs:cor:dmo:050:12, hrn:node:hadronmemory.com:specs:cor:agt:080:24).
joinApp JoinAppPayload! 023-app-shape US2 — user-level install. The currently-logged-in user joins the App as an AppMember without requiring an OrgMember row. App lifecycle checks run before the existing-member return and self-join policy check. #1714: self-join is closed by default. It is open only when the App's primary Agent declares installation_policy.selfJoinRole, which must be one of its memberRoles and is never "owner"; the joiner gets that role. Self-join never assigns owner. Explicit role changes use ensureAppMember, by an App member manager. Idempotent — if the user is already an AppMember of the App, the existing row is returned, before the gate is consulted. Error codes (GraphQLError extensions.code, Error.name style): - UNAUTHENTICATED — no logged-in user in context. - AppNotFoundError — the App does not exist or is soft-deleted. - AppUninstalledError — the App is in the spec-021 soft-uninstall lifecycle phase. - SelfJoinNotAllowedError — the App's Agent has not opted into self-service joining (including an App with no installed Agent). Checked before capacity, so it reveals nothing about maxMembers. - OrphanAppError — the App lost its installed Agents while the join was in flight. - MaxMembersExceededError — the Agent's maxMembers limit is hit. - InvalidRoleError — the picked default role isn't accepted by the Agent's policy (rare; would indicate a policy update race). Accepts the entity's ID or URN.
appId ID!
leaveApp LeaveAppPayload! 023-app-shape US2 — user-level uninstall. The currently-logged-in user leaves an App. Idempotent (no-op when not a member). The user's personal-class Memory at (appId, userId) is NOT cascade-deleted per spec 008 FR-015 — it re-attaches if the user later re-joins. Bound workers require an instruction or their own live app.members grant (hrn:node:hadronmemory.com:specs:cor:dmo:050:12); successful instructed removals/no-ops record the claim. Direct-person cleanup keeps the existing App reference-resolution behavior. Accepts the entity's ID or URN.
appId ID!
instruction ActInstructionInput
createMemoryShare CreateMemorySharePayload! 023-app-shape US3 — asymmetric cross-user grant on a personal-class Memory. The principal (memory.userId) grants a grantee read or write access. Used for the per-pairing pattern (Alice's paired-with-Mentor-A memory is distinct from her paired-with-Mentor-B memory; each gets its own MemoryShare). Upsert semantics: re-calling with a different role on an existing (memoryId, granteeId) pair updates the role rather than throwing. For v1 the caller MUST be the principal themselves (memory.userId === ctx.userId). The Agent-mediated path (App backend acting on the principal's behalf via MCP) is supported by the access-control predicate but not by this GraphQL surface — see the deferred policy discussion linked from joinApp.ts. Share-audience rule (#778): a plain ORG-OWNED personal memory (organizationId set, no agent scope) may be shared ONLY with a current member of that org; a FREE-STANDING (org-less) personal memory may be shared with any user. Agent-scoped personal memories (the spec-023 per-pairing App pattern) are exempt — their audience is governed by AppMember + AgentSubscription, not org membership. Error codes (extensions.code, Error.name style): - UNAUTHENTICATED — no logged-in user in context. - FORBIDDEN — caller is not the Memory's principal. The caller-authority guard runs first and deliberately does not differentiate between a missing/deleted memory and a memory the caller does not own — both return FORBIDDEN before grantee lookup. An owner of a wrong-class memory (for example private) can pass that principal check and receive InvalidMemoryClassForShareError. - MemoryShareGranteeMissingError — granteeId doesn't resolve to an existing User. Only reachable when the caller passes the principal guard. - CrossOrgShareNotAllowedError — the grantee is not a member of an org-owned personal memory's org (the #778 audience rule above). - InvalidMemoryClassForShareError — the principal addressed a memory whose class is not personal; private memories cannot be shared. - MemoryNotFoundForShareError — retained controller-level lifecycle refusal; the ordinary GraphQL principal precheck conceals absence.
memoryId ID!
granteeRef String #769 — the grantee as a reference resolved server-side: a user id, email, handle, or hrn:user:<handle> URN. Resolution sees the full user table, so a cross-org personal-memory share works by email/handle. Supply this OR granteeId.
granteeId ID

⚠️ DEPRECATED

Use granteeRef (accepts id / email / handle / hrn:user URN). Deprecated (#769): the grantee's user PK. Use granteeRef, which also accepts email / handle / URN.
role MemoryShareRole!
deleteMemoryShare DeleteMemorySharePayload! 023-app-shape US3 — delete a MemoryShare. Per FR-022, revocation takes effect on the next read (there's no "deactivated" state; just a row delete). Renamed from revokeMemoryShare in #785. Caller-authority rule (#785) — principal OR self, the same shape removeMemoryMember uses: - The memory's principal (memory.userId) may delete ANY grantee row on their memory. Idempotent: deleting a share that is already gone succeeds. - A GRANTEE may delete THEIR OWN row — the stop-sharing-with-me / leave path. Omit granteeRef entirely and the mutation targets the caller's own share. - Everyone else gets FORBIDDEN. On the self path the SHARE ROW itself is the authorization, so that path is idempotent only up to the row's lifetime: repeating a successful leave answers FORBIDDEN (you already left). That is what keeps every unauthorized outcome identical — a caller who is neither principal nor grantee cannot tell "no such memory" from "not shared with me" from "not yours", by error code or by the difference between an error and a successful no-op. The same rule covers the grantee reference: a non-principal caller gets FORBIDDEN whether the named user exists or not, so neither memories nor users can be enumerated here. (A principal, who by definition already knows the memory exists, still gets NOT_FOUND for a granteeRef that resolves to nobody.) A grantee may leave a memory whose owner has soft-deleted it (the row would otherwise be stranded); the principal path still treats a soft-deleted memory as FORBIDDEN.
memoryRef ID! The memory, by id or URN (#785).
granteeRef String #769 — the grantee as a server-resolved reference (id / email / handle / hrn:user URN). Supply this OR granteeId. Omit BOTH to target the caller's own share (self-removal).
granteeId ID

⚠️ DEPRECATED

Use granteeRef (accepts id / email / handle / hrn:user URN).
updateMemoryShareRole UpdateMemoryShareRolePayload! 023-app-shape US3 — change the role on an existing MemoryShare. Throws MemoryShareNotFoundError if the (memoryId, granteeId) row doesn't exist — use createMemoryShare to upsert. Caller-authority rule matches createMemoryShare.
memoryId ID!
granteeRef String #769 — the grantee as a server-resolved reference (id / email / handle / hrn:user URN). Supply this OR granteeId.
granteeId ID

⚠️ DEPRECATED

Use granteeRef (accepts id / email / handle / hrn:user URN).
role MemoryShareRole!
addMemoryMember AddMemoryMemberPayload! 023-app-shape US4 — add a team member to a group-class Memory. Idempotent on the (memoryId, userId) PK: re-calling with a different role upserts the role. The caller MUST be an owner of the Memory (role = owner). The bootstrap case is handled by createMemory itself, which adds the creator as the first owner of a newly-created group memory. Error codes (extensions.code, Error.name style): - UNAUTHENTICATED — no logged-in user in context. - FORBIDDEN — caller is not an owner of the memory. (Uniform for missing-memory / wrong-class / not-an-owner cases, by the same don't-leak-metadata rule as MemoryShare mutations.) - InvalidMemoryClassForMemberError — memory is not group-class (only reachable from non-GraphQL callers in v1 — the caller-authority guard short-circuits to FORBIDDEN first). - MemoryMemberUserMissingError — the userId doesn't resolve. - LastOwnerProtectedError (FR-038) — reachable via the idempotent upsert path when the call would demote an existing sole owner to reader/writer.
memoryRef String #764 — the memory as an id or URN. Supply this OR memoryId.
memoryId ID

⚠️ DEPRECATED

Use memoryRef (accepts id / URN).
userRef String #764 — the user as an id / email / handle / hrn:user:<handle> URN. Supply this OR userId.
userId ID

⚠️ DEPRECATED

Use userRef (accepts id / email / handle / URN).
role MemoryMemberRole!
updateMemoryMemberRole UpdateMemoryMemberRolePayload! 023-app-shape US4 — change the role on an existing team member. Throws MemoryMemberNotFoundError when the row doesn't exist; use addMemoryMember to upsert. Throws LastOwnerProtectedError (FR-038) when demoting the sole remaining owner. Caller-authority rule matches addMemoryMember. Error codes (extensions.code, Error.name style): - UNAUTHENTICATED — no logged-in user in context. - FORBIDDEN — caller is not an owner of a live group memory. - MemoryNotFoundForMemberError — memory absent or soft-deleted (only reachable from non-GraphQL callers in v1 — the guard short-circuits to FORBIDDEN first). - InvalidMemoryClassForMemberError — memory is not group-class (same; guard short-circuits to FORBIDDEN first). - MemoryMemberNotFoundError — no row at (memoryId, userId). - LastOwnerProtectedError (FR-038) — would demote the sole owner.
memoryRef String #764 — the memory as an id or URN. Supply this OR memoryId.
memoryId ID

⚠️ DEPRECATED

Use memoryRef (accepts id / URN).
userRef String #764 — the user as an id / email / handle / hrn:user:<handle> URN. Supply this OR userId.
userId ID

⚠️ DEPRECATED

Use userRef (accepts id / email / handle / URN).
role MemoryMemberRole!
removeMemoryMember RemoveMemoryMemberPayload! 023-app-shape US4 — remove a team member. Idempotent. Removing the LAST owner is rejected with LastOwnerProtectedError (FR-038) — group memories must always have ≥1 owner; the path to fully empty one is to delete the Memory. Removing the last non-owner does NOT delete the Memory (FR-031); the row persists with its remaining owner(s). Caller-authority: either an owner of the Memory, or the member being removed (self-removal).
memoryRef String #764 — the memory as an id or URN. Supply this OR memoryId.
memoryId ID

⚠️ DEPRECATED

Use memoryRef (accepts id / URN).
userRef String #764 — the user as an id / email / handle / hrn:user:<handle> URN. Supply this OR userId.
userId ID

⚠️ DEPRECATED

Use userRef (accepts id / email / handle / URN).
publishAgentImport AgentImport! Publish a dependency edge from a parent Agent to an imported Agent (008-agent-installation FR-005). v1 supports 1-level imports only: the imported Agent must not itself be a parent of any other import. Authorization: ADMIN/OWNER of the parent Agent's owning org. The parent's owning org MUST hold an active AgentOrgGrant for the imported Agent — bundling requires the same kind of license that installation does. Accepts the entity's ID or URN for both Agent ids.
parentAgentRef ID!
importedAgentRef ID!
position Int!
required Boolean
removeAgentImport Boolean! Delete a dependency edge between two Agents. Idempotent (no-op when the row doesn't exist). Apps that already installed the imported Agent are unaffected; removing the import only stops *future* parent installs from cascading the dep. Accepts the entity's ID or URN.
parentAgentRef ID!
importedAgentRef ID!
createAppKey AppKeyCreated! Mint a new AppKey for an App. Only whoever manages the App, as themselves (hrn:node:hadronmemory.com:specs:cor:dmo:050:05; hrn:node:hadronmemory.com:specs:cor:acl:010:01). Person-only (hrn:node:hadronmemory.com:specs:cor:dmo:050:12, #3277): never a worker session in any shape, a run principal, an impersonation or an App key, even when the worker's holder manages the App. New keys hold no scopes. Granting or revoking scopes uses the same manager audience. Accepts the entity's ID or URN.
appRef ID!
label String
revokeAppKey Boolean! Revoke an AppKey. Only whoever manages the App, as themselves, or through their held worker on a validated `instruction` (hrn:node:hadronmemory.com:specs:cor:dmo:050:12 S6, ruling 0098; hrn:node:hadronmemory.com:specs:cor:dmo:050:05; hrn:node:hadronmemory.com:specs:cor:acl:010:01). Never an App key, a host-launched or uninstructed worker session, a run or an impersonated request. A worker session that is refused cannot tell a missing key from an existing one. An admitted instructed revoke records one team event (never the key id); a key already revoked records none. AppKey has no URN; the id is raw ID-only.
id ID!
instruction ActInstructionInput
grantAppKeyScope AppKey! #1749 — give an App key a scope (hrn:node:hadronmemory.com:specs:cor:aut:010:04). Only whoever manages the App, as themselves: never an App key, a worker's session or an impersonation (person-only: giving a grant, hrn:node:hadronmemory.com:specs:cor:dmo:050:12, #3277). Granting a scope the key holds changes nothing. A new key, and a rotated one, holds none. Unknown scope: BAD_USER_INPUT. #1709: host:operate is granted for ONE host, named by hostId (hrn:node:hadronmemory.com:specs:cor:agt:070:04), and hostId is refused for any other scope. A key already operating as another host is refused APP_KEY_SCOPE_HOST_CONFLICT: revoke host:operate first.
id ID!
scope String!
hostId String
revokeAppKeyScope AppKey! #1749 — take a scope back. The key's next call is refused. Revoking a scope it does not hold changes nothing. Whoever manages the App, as themselves, or through their held worker on a validated instruction (hrn:node:hadronmemory.com:specs:cor:dmo:050:12 S6, ruling 0109 A); an admitted instructed revoke that ended a scope records one team event (never the key or scope id).
id ID!
scope String!
instruction ActInstructionInput
createUserApiKey UserApiKeyCreateResult! 025-oauth-for-mcp FR-004: mint a new user-scoped API key for the calling User. Returns the raw key exactly once (the server stores only the SHA-256 hash). Rejected with UNAUTHENTICATED for AppKey- resolved callers (no user in context). Impersonation is refused; an MCP-only OAuth credential cannot mint API keys. label is optional and limited to 200 JavaScript string code units. Minting from a user API key retains its minting-key ancestry and sign-in root; an ended sign-in root refuses minting.
label String
revokeUserApiKey UserApiKey! 025-oauth-for-mcp FR-004: revoke a user-scoped API key owned by the calling User, together with every recorded descendant. Unrelated roots and siblings stay live; unknown legacy parents are not inferred. Returns the named UserApiKey with its revokedAt. Idempotent for already-revoked keys. NOT_FOUND for both unknown and foreign keys; UNAUTHENTICATED for AppKey-resolved callers.
id ID!
setUserApiKeyHidden UserApiKey! #2298: hide (or unhide) one of the caller's own REVOKED API keys in the default myUserApiKeys list. Hiding an active key is refused with BAD_USER_INPUT, reason KEY_ACTIVE, and changes nothing. Idempotent: the first hiddenAt is kept. Touches no validity, revocation time, lineage or descendant. Same authority as revokeUserApiKey (own user only; unknown and foreign ids are NOT_FOUND).
id ID!
hidden Boolean!
deleteUserApiKey UserApiKeyDeletion! #2659 (hrn:node:hadronmemory.com:specs:cor:dmo:070:03): delete one of the caller's own API keys, live or revoked. A live key is revoked first, with every key it minted, in the same step, so no working credential is left behind. The keys it minted are not deleted and do not prevent the delete: they stay, revoked, with no parent. The key then no longer authenticates and is absent from myUserApiKeys whatever includeHidden says. Returns the one append-only deletion record (no secret, no hash). Only the key's own user, as themselves: FORBIDDEN under impersonation, from a worker session or a run; UNAUTHENTICATED for AppKey-resolved callers. NOT_FOUND for both unknown and foreign keys, as revokeUserApiKey answers. To tidy the list without deleting, hide a revoked key with setUserApiKeyHidden instead.
id ID!
revokeAgentSubscription AgentSubscription! 005-agent-subscription FR-023 + FR-028 + FR-029: revoke a user's AgentSubscription. Authorized for ADMIN/OWNER of the Agent's owning org. Side effect: empty personal Memory of (user, agent) is hard- deleted; non-empty is retained with userMemoryOfAgentId preserved. Accepts the entity's ID or URN (agentId).
userRef String #764 — the user as an id / email / handle / hrn:user:<handle> URN. Supply this OR userId.
userId ID

⚠️ DEPRECATED

Use userRef (accepts id / email / handle / URN).
agentRef String #764 — the Agent as an id / URN. Supply this OR agentId.
agentId ID

⚠️ DEPRECATED

Use agentRef (accepts id / URN).
createAppUser User! App Key callers only: vouch for a user, creating (or returning) the User this App knows by `externalId`. Managing that user's SESSIONS is the startAgentSession / endAgentSession pair below, not this call. The legacy email argument accepts only empty values; identity addresses are established through verified sign-in.
externalId String!
handle String
name String
email String
startAgentSession Session! Multi-user-agent session lifecycle (renamed to avoid collision with the developer/guided startSession and endSession mutations). Supply a base64-encoded 32-byte key beside the operation through the x-hadron-operation-key header when identifyUserMethod is SECRET. The key is verified for an existing encrypted memory and held only after the new session commits; USER_ID mode rejects key supply. Only one key-consuming operation may use the header in a request; a second attempt is BAD_UNLOCK_INPUT.
agentId ID!
externalUserId String
sessionTimeoutSeconds Int
endAgentSession Boolean!
sessionId ID!
linkMemoryToUser Memory! Link this App's live plaintext anonymous memory to a real user. Providing x-hadron-operation-key in the request header claims private ownership and encrypts live nodes; remaining fields and history complete in bounded passes. Only one key-consuming operation may use the header per request; a second is BAD_UNLOCK_INPUT. After a committed claim, interrupted completion allows the strict owner or owning App key to call encryptMemory with the existing key. A registered holding cannot be linked again. Accepts the entity's ID or URN.
memoryId ID!
externalUserId String!
encryptMemory Memory! Convert a plaintext PRIVATE memory to encrypted (spec 041, caller-held keys). Exactly one of dataKey (base64, 32 bytes) / passphrase (scrypt- derived; salt + params stored on the memory, the key itself never). First encryption requires the strict owner. The owning App key may only complete already-encrypted private memory using its existing dataKey and matching verifier; impersonation and sibling Apps grant no authority. Live and historical node fields are converted in bounded locked passes. One-way without the key: the server cannot recover the content. The secret travels beside the operation, never in it (hrn:node:hadronmemory.com:specs:cor:sec:040:04, #1796). The strict owner sends exactly one of dataKey or passphrase in an x-hadron-memory-keys entry naming this memory; on a first encryption that entry establishes the verifier, and it counts only when encryptMemory is the operation's sole root field. The owning App sends its key in x-hadron-operation-key, for completion only. Accepts the entity's ID or URN.
memoryId ID!
dataKey String

⚠️ DEPRECATED

Send the key in x-hadron-memory-keys, or x-hadron-operation-key for an owning App's completion.
passphrase String

⚠️ DEPRECATED

Send the passphrase in x-hadron-memory-keys.

Objects

AccessGrant

issue #323: one reason a subject has (or would have) access to a resource.

Field Argument Type Description
source AccessSource!
role String! The role/level this particular grant confers.
via String Human label for the grant's origin (owning org URN, the inherited memory URN, the app URN, etc.); null when the grant has no distinct origin.

AccountUsageAccount

3853 — one usage account an App has history for (hrn:node:hadronmemory.com:specs:cor:agt:140:05): the label, host and family

that together are an account (hrn:node:hadronmemory.com:specs:cor:agt:140:01). Passed back to accountUsageProjection as account, host and family, every entry is accepted. workers and workersConfigured are the newest snapshot's.

Field Argument Type Description
account String!
host String!
family String!
newestSnapshotAt DateTime!
workers [String!]!
workersConfigured Boolean!

AccountUsageAccounts

3853 — the accounts an App has usage history for. complete is false when more exist than the bound

(hrn:node:hadronmemory.com:specs:cor:agt:140:05); a cut list is not a refusal.

Field Argument Type Description
asOf DateTime!
accounts [AccountUsageAccount!]!
complete Boolean!

AccountUsageBurnRange

3820 — percentage points of a window used per hour.

Field Argument Type Description
lowPctPerHour Float!
highPctPerHour Float!

AccountUsageMoveTarget

3820 — the other account of a moved worker, before and after.

Field Argument Type Description
account String!
baseline [AccountUsageWindowProjection!]!
adjusted [AccountUsageWindowProjection!]!

AccountUsageProjection

3820 — one account's projection. workers are the names the collector configured on the account.

Field Argument Type Description
account String!
family String
host String
asOf DateTime!
newestSnapshotAt DateTime
workers [String!]!
workersConfigured Boolean!
windows [AccountUsageWindowProjection!]!
whatIf AccountUsageWhatIf

AccountUsageWhatIf

3820 — the what-if: the asked account's windows after the change, and, for a move, the target account's.

Field Argument Type Description
adjusted [AccountUsageWindowProjection!]!
target AccountUsageMoveTarget

AccountUsageWindowProjection

3820 — one window of one account.

Field Argument Type Description
window AccountUsageWindow!
lengthMinutes Int! The window's length in minutes.
status AccountUsageStatus!
reason AccountUsageReason
usedPct Float Used share at the newest snapshot, 0 to 100.
resetsAt DateTime
observedAt DateTime When the newest snapshot of this window was observed.
lowPctAtReset Float Projected use at the reset, lower and upper end of the range, each capped at 100.
highPctAtReset Float
burn AccountUsageBurnRange The account's burn range over the lookbacks.
perWorkerBurn AccountUsageBurnRange The account's burn divided by the workers configured on it; null when none are.
confidence AccountUsageConfidence
shape AccountUsageShape
runsOutAt DateTime Only when even the lower end of the range reaches 100% before the reset.
ceilingPct Float! The token ceiling (85) that canAddWorker's token constraint compares the projected use to.

AcknowledgeWakesResult

Field Argument Type Description
acknowledged Int! Wakes that moved the delivery record.
unchanged Int! Repeats: already delivered, counted nowhere twice.

ActionRegisterIndexEntry

3287 — one row of the action-register index: one code, its winning entry and its task for the asking Agent.

Field Argument Type Description
code String!
state ActionRegisterIndexState!
actionUrn String hrn:action:<root>:<agent-slug>:<code>, keyed on the Agent whose system memory holds the winning entry. Null when UNMAPPED.
entryUrn String The winning register:<code> node's URN. Null when UNMAPPED.
definedBy String The URN of the Agent whose system memory holds the winning entry (so an override shows). Null when UNMAPPED.
taskLoc String The entry's task loc. Null when UNMAPPED.
taskUrn String The asking Agent's nearest runnable task at taskLoc. Set only when MAPPED.

ActionRegisterIndexPage

3287 — a page of the action-register index; total and hasMore count after the read gate and the filters.

Field Argument Type Description
entries [ActionRegisterIndexEntry!]!
total Int!
hasMore Boolean!

ActionTicket

One consumable ticket in the org ledger (cor:acl:050:04 tier 2).

Field Argument Type Description
id ID!
organizationId ID!
appId ID
action String!
mintedBy String!
note String
consumedByRunId ID
consumedAt DateTime
expiresAt DateTime
createdAt DateTime!

ActionTicketsPage

Field Argument Type Description
items [ActionTicket!]!
total Int!

ActorRef

1610 — public identity of a Worker or Agent that wrote a node: never the full object, whose own read gate this does not pass.

Field Argument Type Description
id ID!
name String!
urn String The canonical hrn:worker:/hrn:agent: URN. Null when it cannot be composed.

AddMemoryMemberPayload

Field Argument Type Description
memoryMember MemoryMember!

Agent

The reusable definition a Builder creates and the marketplace can list. Agents are installed into runtime Apps through the AppAgent N:M join: an App may install many Agents, and an Agent may be installed in many Apps. The App, not the Agent, is the org- or user-owned caller identity and deployment.

Field Argument Type Description
id ID!
organizationId String
urn String!
name String!
description String
bootPromptRef String #2045 — the canonical URN of the compiled boot prompt this Agent's pointer names now (a moved node shows its new URN; a hard-deleted one its URN at write time). Null when no pointer is set OR when the caller may not see it (only a caller who may read the Agent's system memory): null is not proof that no pointer exists.
bootPromptTargetDeleted Boolean #2045 — whether the pointer's target is deleted (soft or hard): true / false, and null when no pointer is set or the caller may not see it. Same gate as bootPromptRef. Nothing is served from a deleted target (R27).
bootPromptServe BootPromptServeOutcome #2708 — what this Agent's OWN pointer would serve now (hrn:node:hadronmemory.com:specs:cor:agt:040:10): the Agent's own compiled prompt, saying nothing about an App install or a worker that overrides it (see AppAgent.bootPromptServe and Worker.bootPromptServe). Computed by the resolver a bind uses, so it never substitutes a fallback. Null when the caller may not see it (same gate as bootPromptRef), which is judged before anything is resolved.
systemMemoryId String
visibility AgentVisibility!
listedOnMarketplace Boolean! cor:acl:080:04 — opt-in marketplace catalogue flag (advertisement, not access).
usesTasks Boolean! #2138: false means every Worker cast from this Agent counts as having a task and is expected to check its team channel every period (coordinators, the lifecycle agent). Default true.
resetContextAfterTask Boolean! #2162 (hrn:node:hadronmemory.com:specs:cor:agt:050:27): when a task one of this Agent's workers had started finishes or is cancelled, and it holds no other started task, its host resets the worker's context (a shed: the binding and session stay). Default false. Set by whoever manages the Agent.
lifecycle AgentLifecycle! #4224 (S3 of #4229): how long this Agent's workers run. LONG_LIVED (default): a worker's process should always run. SHORT_LIVED: only while the worker is the assignee of a pending or started task, one waiting on its child tasks included. Read by hostDesiredState at each call; changing it moves no session or process by itself. #4223 (hrn:node:hadronmemory.com:specs:cor:agt:050:10, Proposed there): for a SHORT_LIVED Agent's worker a task's closeSessionWhenDone is not read; the worker is asked to end its session when the last pending or started task assigned to it finishes or is cancelled, never while another is open, and no context reset is requested (resetContextAfterTask is not read). A worker marked leave-alone keeps the ordinary rule. Set by whoever manages the Agent, like usesTasks.
contextCap Int #4225 (S4b of #4229; hrn:node:hadronmemory.com:specs:cor:agt:050:27 part 12, Proposed; G4): the context size, in tokens, above which a worker of this LONG_LIVED Agent whose host reports it idle at an empty prompt is reset (one worker.reset-context, at most one an hour per worker). Null (the default) is no cap. A busy worker is never reset for it, and a SHORT_LIVED Agent's workers ignore it. Set by whoever manages the Agent.
type AgentType!
surfaces [String!]!
personaRole String Persona role - free string with conventions ('backend-engineer').
extendsAgentId ID #1885 (hrn:node:hadronmemory.com:specs:cor:dmo:050:14) - the id of the one base Agent this Agent extends, or null. Set, change or clear it with setAgentBase.
extendedBy AgentExtensionPage! #2177 - the Agents that DIRECTLY extend this one (not their extenders), in name order, that you may read exactly as you read agent(ref:). Visibility is applied before the page is cut. first: 1-50, default 20. "after" is an opaque token from a previous page's endCursor: it expires after 15 minutes, is bound to this Agent and to you, and a refused token is always the same "invalid cursor" error. An EMPTY page with hasMore true means the scan is incomplete, NOT that nothing readable remains: keep paging. There is deliberately no total.
first Int
after String
offerReadiness AgentOfferReadiness #2246 (hrn:node:hadronmemory.com:specs:cor:dmo:050:19) - is this Agent ready to be offered to other organisations: could an organisation with no relation to it subscribe to, install and clone it as it stands, and if not, why. Readable only by whoever manages the Agent (hrn:node:hadronmemory.com:specs:cor:dmo:050:13); null for everyone else, readers of a PUBLIC Agent included, and when the Agent is gone. A reason names a memory or Agent only if you may read it; otherwise only the count shows. Answers for an outsider, so a non-PUBLIC Agent is not ready even though its own manager can still clone it. Read-only; grants nothing.
clonedFromAgentRef String #2281 - the URN of the Agent this one was cloned from (cloneAgent), as that Agent's current URN. Null when this is not a clone, when you cannot read the source, when the source was deleted, or when the clone's origin identity is not recorded: those cases are indistinguishable by design. Never an id or an object.
tasksIndexRef ID #1892 (hrn:node:hadronmemory.com:specs:cor:dmo:050:15) - the id of the index node whose incoming, trigger-labelled edges list this Agent's own tasks, or null. Set or clear it with setAgentIndexRefs; read the Agent's whole task list with agentTaskList.
processesIndexRef ID #1892 (hrn:node:hadronmemory.com:specs:cor:dmo:050:16) - the id of the index node whose incoming, trigger-labelled edges list the processes this Agent starts or owns, or null. Set or clear it with setAgentIndexRefs; read the Agent's processes with agentProcessList.
aiProvider String
aiModel String
hasAiApiKey Boolean!
aiApiKeyPreview String
properties JSON
memoryItems [AgentMemoryItem!]!
memoryProvisioning MemoryProvisioning!
installationPolicy InstallationPolicy!
registerDefaults RegisterDefaults! Spec 049 Phase 5 — the defaults this Agent's install-created register row is made with.
imports [AgentImport!]!
importedBy [AgentImport!]!
apps [App!]! Apps that have this Agent installed (via the AppAgent join). After spec 023-app-shape, an App can install multiple Agents; this list contains every App where THIS Agent is one of the installed ones. #551: these are OTHER tenants' App objects (whose keys/members are not re-gated at the field level), so — unlike the Agent's own fields — this is NOT public on a PUBLIC agent. Scoped to Apps in orgs the CALLER belongs to (platform ADMIN/OWNER: all); a non-member gets an empty list.
appAgents [AppAgent!]! 023-app-shape: the AppAgent join rows where this Agent is installed. Use App.appAgents to get the join rows from the App side. #551: same caller-org scope as apps — never exposes a foreign org's App.
appCount Int! Adoption count. #551: the owning tenant's view (0 otherwise): the owning org's members, or for a user-owned agent its owner (#1693).
orgGrants [AgentOrgGrant!]! Org grants for this Agent (which orgs were granted it). #551: the agent's customer list — visible to members of the Agent's owning org only (empty otherwise), regardless of the agent's PUBLIC visibility.
createdAt DateTime!
tickerTemplates [AgentTickerTemplate!]! #2024 — the tickers this Agent declares. Casting a worker from it creates them for the worker (a snapshot: later edits reach only future casts). Readable by anyone who can read the Agent.
viewerMayEditTickerTemplates Boolean #2024 — whether the caller may create, change or delete this Agent's ticker templates (the Agent ADMIN door, the same as editing the Agent). Null when it cannot be decided.

AgentAIConfig

Decrypted AI config for an agent — the portal backend uses it to make LLM calls on behalf of the logged-in user.

Gated by requireOwnerOrOrgRole, which branches on the Agent's OWNERSHIP CLASS: an org-owned Agent admits an ADMIN of that org (and a platform admin), while a USER-owned one (ownerUserId set, organizationId null) admits only its owner — strictly, with no org path and no admin bypass. Published as "only returned to org admins" until #1232, which is the org-owned half of the rule.

036-ai-service-config: registry-backed (the Agent's config named 'default'); prefer resolveAIConfig for new callers.

Field Argument Type Description
provider String!
apiKey String!
model String!

AgentExtensionPage

2177 - one page of Agent.extendedBy.

Field Argument Type Description
items [Agent!]!
endCursor String Opaque. Null when hasMore is false.
hasMore Boolean!

AgentImport

008-agent-installation: Agent dependency edge ("Suite imports Calendar"). v1 enforces 1-level imports only.

Field Argument Type Description
parentAgentId ID!
importedAgentId ID!
parentAgent Agent The parent Agent when this caller may read its definition.
importedAgent Agent The dependency Agent when this caller may read its definition; a builder grant alone does not grant that read.
position Int!
required Boolean!
createdAt DateTime!

AgentListedProcess

1892 (hrn:node:hadronmemory.com:specs:cor:dmo:050:16) - one process on an Agent's process list.

Field Argument Type Description
node Node!
kind AgentProcessKind!
trigger String The name of the index edge that lists it, for STARTS; always null for INVOLVED.

AgentListedTask

1892 (hrn:node:hadronmemory.com:specs:cor:dmo:050:15) - one task on an Agent's task list.

Field Argument Type Description
node Node! The task. A base's task, listed through the Agent, keeps its own URN and carries inheritedFrom.
trigger String The name of the index edge that lists it; null for a task no index edge lists.
matchedBy AgentTaskMatchedBy #2421 experimental symptom search: which retriever ranked this task; null on the unfiltered list.

AgentMemoryItem

Field Argument Type Description
id ID!
memory Memory!
role String!
createdAt DateTime!

AgentOfferReadiness

2246 - whether another organisation could subscribe to, install and clone the Agent as it stands.

Field Argument Type Description
ready Boolean!
reasons [AgentOfferReason!]! Every reason that holds, in the clone refusal's order. Empty exactly when ready.

AgentOfferReason

2246 - one reason an Agent is not ready to be offered. count is every blocked subject; subjects are at

most 20 of the ones you may read; omittedByCap are readable ones past the cap; hiddenByAccess are ones you may not read, never named. subjects + omittedByCap + hiddenByAccess = count.

Field Argument Type Description
code AgentOfferReasonCode!
count Int!
subjects [AgentOfferSubject!]!
omittedByCap Int!
hiddenByAccess Int!

AgentOfferSubject

2246 - the name of one blocking subject, shown only because you may read it. Nothing else about it is reachable.

Field Argument Type Description
name String!

AgentOrgGrant

008-agent-installation: Org↔Agent license. Authorizes (a) creating an App in this Org that uses this Agent, and (b) bundling this Agent in an AgentImport edge of an Agent the Org owns. Sibling to AgentSubscription.

Field Argument Type Description
orgId ID!
agentId ID!
organization Organization The customer Organization when the caller may read it; a vendor grant alone does not authorize it.
agent Agent The licensed Agent when this caller may read its definition.
activatedAt DateTime
expiresAt DateTime
revokedAt DateTime
revokedBy ID
isActive Boolean!
createdAt DateTime!

AgentSchedule

Recurring trigger (cor:agt:010, D-2026-07-04-E).

Field Argument Type Description
budgetTokens Int Optional per-run token limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
budgetActions Int Optional per-run action limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
id ID!
organizationId ID!
appId ID!
agentId ID
userId ID On-behalf-of user captured at creation; v1 only the creator themself.
scopeId ID Spec 049: the scope this trigger's runs carry (null ⇒ 'app').
name String!
cron String 5-field cron for recurring schedules; null for one-shots (#510).
runAt DateTime One-shot instant (#510); null for recurring schedules. XOR with cron.
timezone String!
entryNodeUrn String!
eventData JSON
policy JSON
aiConfigName String
enabled Boolean!
lastRunAt DateTime
nextRunAt DateTime
createdAt DateTime!
createdBy String

AgentSchedulePreview

3457: the preview of a schedule that does not exist yet. A snapshot, not a promise: if the graph changes before Create, the hash differs. summary.schedule carries the raw cron, so a plain-language UI renders its own timing.

Field Argument Type Description
outcome AgentSchedulePreviewOutcome!
hash String The pin hash the created schedule's automationApproval.hash shows while the graph is unchanged. Null when CANNOT_BE_ADOPTED.
summary AutomationSummary
reason AgentSchedulePreviewReason

AgentSchedulesPage

Field Argument Type Description
items [AgentSchedule!]!
total Int!

AgentServedBootPrompt

3843 / hrn:node:hadronmemory.com:specs:cor:agt:040:05, hrn:node:hadronmemory.com:specs:cor:agt:040:10: the compiled

boot prompt a chat or run with an Agent (in an App) would be given now, rendered, for a caller that binds no worker.

Field Argument Type Description
decision BootPromptServeDecision! The revision served: the same identity fields as bootPromptServe and a ServedPrompt record.
text String! The served revision's text with its platform variables filled as a chat or run fills them (hrn:node:hadronmemory.com:specs:cor:dmo:150:08): worker.name is the Agent's name, worker.role its persona role, reports-to, signature and trailer are empty, and session.llmModel is the client-reported model or empty. No derived blocks are appended: they belong to a worker's briefing (Worker.prompt).

AgentSubscription

Field Argument Type Description
userId ID!
agentId ID!
user User
agent Agent
activatedAt DateTime
expiresAt DateTime
revokedAt DateTime
revokedBy ID
isActive Boolean!
createdAt DateTime!

AgentSubscriptionPage

2213 — one page of agent subscriptions.

Field Argument Type Description
items [AgentSubscription!]!
total Int!
hasMore Boolean!

AgentTask

One piece of work a team App has assigned, or wants assigned (hrn:node:hadronmemory.com:specs:cor:agt:050:01). The platform records who holds it, since when and how it ended; it never reads what the work is. Readable by the App's participants, workers acting through their sessions included (hrn:node:hadronmemory.com:specs:cor:agt:050:21).

Field Argument Type Description
matchSkipped [AgentTaskSkippedCandidate!] #3816 (V21-V23, hrn:node:hadronmemory.com:specs:cor:agt:050:01): the candidates a failed match skipped, each with EVERY reason it was skipped, in the enum's declared order. Returned only in the createAgentTask(match: true) answer; never stored, so any later read is null (as is a match that assigned, and a create without match: true).
matchFailure AgentTaskMatchFailure Null unless an opt-in single-shot match failed. No assignment-unassignable alarm is raised for it.
runSettings AgentTaskRunSettings #4291 (hrn:node:hadronmemory.com:specs:cor:agt:050:01): the task's own run settings (what a start for it launches); null when it names none.
appliedRunSettings AgentTaskAppliedRunSettings #4291 (hrn:node:hadronmemory.com:specs:cor:agt:050:01): the settings the run actually used, from the assignee's open session when the task was started. Null until then, for a task a person runs, and when that session had reported none. Read it beside runSettings: a worker that was already running keeps its session's settings, so the two can differ. A hand-back clears it; a reassignment of a started task does not restamp it.
priority Int! #2644 (hrn:node:hadronmemory.com:specs:cor:agt:050:01) — priority1 is highest; range1..5, default1. Matching only, never authority.
blocked Boolean! Whether at least one blocker remains open. Never a status; manual assignment is preserved.
overdue Boolean! #2654: true exactly when the overdue filter of the task list would list this task at the moment of the read (same rule, judged on the server clock). A client shows this field and computes no overdue predicate of its own.
blockedBy AgentTaskDependencyPage! Same-App tasks this task waits for, including ended blockers.
limit Int
offset Int
blocks AgentTaskDependencyPage! Same-App tasks that name this task as a blocker.
limit Int
offset Int
clonedFrom AgentTask #2646 (hrn:node:hadronmemory.com:specs:cor:agt:050:02): the task this one was cloned from, or null when it was not made by a clone or the source is not readable to you. Read it as "replaces" when the source's status is FINISHED or CANCELLED, and "cloned from" otherwise.
clones AgentTaskDependencyPage! #2646: the clones made from this task, in its own App, paged (hrn:node:hadronmemory.com:specs:cor:agt:050:02); a clone you cannot read is left out.
limit Int
offset Int
id ID!
appId ID!
handle String! The short handle of this task, for example "AT3.405": its project (AT3, a top-level task counted per App) and its number within each parent down to it (hrn:node:hadronmemory.com:specs:cor:agt:050:01). "AT0" is the reserved project "No project": a task made with no project is AT0.<n>. An alias for the id, which stays canonical; every task operation that takes a task id also takes the handle. Immutable: parentage is fixed at creation. A person who belongs to several Apps qualifies it as hrn:agenttask:<app-urn>:AT3.405, where the App URN is the App's urn. The handle is not the number of any GitHub issue the task's source names.
taskNumber String! This task's own number inside its handle (the last segment), counted per parent. Permanent: never changed, never given to another task.
title String!
description String
source String Opaque origin reference (an issue URL, a node URN). Not interpreted.
externalId String #3125 S2 (hrn:node:hadronmemory.com:specs:cor:agt:120:02): the outside item this task claims (an issue's canonical URL), set once at creation and never edited. Unique within the App, whatever the task's state. Null when none.
portalUrl String #4084 (hrn:node:hadronmemory.com:specs:cor:agt:120) — the portal page that opens this task, <FRONTEND_URL>/app/apps/<appId>/tasks/<taskId>, printed by the server so no client builds it. Null when FRONTEND_URL is unset or malformed (as Node.portalUrl).
parentTaskId ID Null for a root task.
owner AgentTaskParty!
assignee AgentTaskParty Null while the task is queued.
requirements AgentTaskRequirements
properties JSON #2420 (hrn:node:hadronmemory.com:specs:cor:agt:050:28): this task's OWN optional JSON object, which the team organises into its own namespaces (review schedule, complexity, a seat's reviewed head). The platform stores and returns it and never reads a key: it is not matcher input and not authorization input. Nothing is inherited, so a child returns its own value (null when unset), never its root's; read the root task for that. Null when none.
status AgentTaskStatus!
queued Boolean! Derived (hrn:node:hadronmemory.com:specs:cor:agt:050:03): pending with no assignee. Never stored.
waitingOnChildren Boolean! Derived (hrn:node:hadronmemory.com:specs:cor:agt:050:04): started with at least one pending or started child task. Never stored.
startBy DateTime
finishBy DateTime The finish-by deadline (#2648, hrn:node:hadronmemory.com:specs:cor:agt:050:14). While set, no stall window applies to the task; one stall.finish-by alarm is raised once it passes with the task neither finished nor cancelled.
startedAt DateTime
finishedAt DateTime
cancelledAt DateTime
result AgentTaskResult Set only on a finished task.
findingDispositions AgentTaskFindingDispositionPage! #2663: dispositions beside the result, same readers; default20/max200/limit0 count-only (hrn:node:hadronmemory.com:specs:cor:agt:050:30).
limit Int
offset Int
findingDisposition AgentTaskFindingDisposition #3325: the one current disposition stored for this finding id on THIS task, or null (undisposed, unknown and other-task ids are indistinguishable). Exact id match; same readers as findingDispositions.
findingId String!
handBack AgentTaskHandBack #2651: the task's latest hand-back by its assignee (hrn:node:hadronmemory.com:specs:cor:agt:050:29); null when it was never handed back. A later hand-back replaces it; every earlier code stays in the task.handed-back events.
tags [String!]!
references [AgentTaskReference!]! #2649 (hrn:node:hadronmemory.com:specs:cor:agt:050:01): the task's ordered, typed references to other things. Each target is the string as stored: never fetched or resolved, so it says nothing about the target's content or whether it exists. Empty when none.
closeSessionWhenDone Boolean! Whether finishing or cancelling asks the assignee to end its worker session (hrn:node:hadronmemory.com:specs:cor:agt:050:10). Set by whoever assigns. #1709: carried out; see sessionEndRequest. #4223: not read for a worker of a SHORT_LIVED Agent (Agent.lifecycle), whose session ends with its last open task.
sessionEndRequest AgentTaskSessionEndRequest #1709 — the request this task's finish or cancellation made that its worker assignee end its session (hrn:node:hadronmemory.com:specs:cor:agt:050:10); null when none was made (closeSessionWhenDone false, a person assignee, or no open session; #4223: for a worker of a SHORT_LIVED Agent, another pending or started task is still assigned to it). Reassigning such a worker's last pending or started task away asks that former assignee too, by a wake and never here: this field shows only the latest request made of the task's current worker assignee, is null for a task assigned to a person or to nobody, and is null for a reader that is another worker. A worker that finishes its own task reads it here: end the session, with a handoff, before dueAt, or the platform ends it through a live host.
assignedAt DateTime
assignedBy AgentTaskParty
createdAt DateTime!
createdBy AgentTaskParty
createdByRunId ID The headless run that created the task (hrn:node:hadronmemory.com:specs:cor:agt:050:06); then createdBy is null.
updatedAt DateTime

AgentTaskAppliedRunSettings

4291 (hrn:node:hadronmemory.com:specs:cor:agt:050:01): the settings a task's run actually used: its worker assignee's newest open

session's family, model and effort, read when the task was started. Each is null when that session had not reported it.

Field Argument Type Description
family String
model String
effort EffortLevel

AgentTaskDependencyPage

Field Argument Type Description
items [AgentTask!]!
total Int!
hasMore Boolean!

AgentTaskExternalIdChange

4084 (hrn:node:hadronmemory.com:specs:cor:agt:120): one change to a task with an external id.

Field Argument Type Description
cursor String! Opaque; pass it as after to read the changes that follow this one.
at DateTime!
kind AgentTaskExternalIdChangeKind!
externalId String! The task's external id, or for RELEASED the id the release cleared.
task AgentTask! The task as it is now.

AgentTaskExternalIdChangePage

4084: one page of agentTaskExternalIdChanges and whether more remain (hrn:node:hadronmemory.com:specs:cor:api:120:04).

Field Argument Type Description
changes [AgentTaskExternalIdChange!]!
hasMore Boolean!
nextCursor String The cursor to pass as after when hasMore; null on the last page.

AgentTaskFinding

2662: immutable finding set at finish; text never enters the event stream.

Field Argument Type Description
id String!
severity AgentTaskFindingSeverity!
text String!

AgentTaskFindingDisposition

2663: latest disposition, separate from immutable findings. Every code, including deferred, resolves the finding.

Field Argument Type Description
findingId String!
disposition AgentTaskFindingDispositionCode!
reference AgentTaskReference

AgentTaskFindingDispositionPage

2663: current dispositions, ordered by finding order, capped pages.

Field Argument Type Description
items [AgentTaskFindingDisposition!]!
total Int!
hasMore Boolean!

AgentTaskFindingPage

2662: findings in supplied order, capped pages (hrn:node:hadronmemory.com:specs:cor:api:120:04).

Field Argument Type Description
items [AgentTaskFinding!]!
total Int!
hasMore Boolean!

AgentTaskHandBack

2651: a task's latest hand-back (hrn:node:hadronmemory.com:specs:cor:agt:050:01, :29), readable by whoever may read the task.

Field Argument Type Description
code AgentTaskHandBackCode!
text String The optional reason text, up to 2,000 characters. Stored on the task only, never in an event.
handedBackAt DateTime!

AgentTaskMatchFailure

Single-shot failure (hrn:node:hadronmemory.com:specs:cor:agt:050:01): assigning clears it; cancellation clears it.

Field Argument Type Description
reason String!
failedAt DateTime!

AgentTaskParty

A task's owner, assignee or audit actor, as a sanitized projection: the Worker's name and URN, or the person's handle. Never the User object, so a task never exposes another person's account fields.

Field Argument Type Description
kind AgentTaskPartyKind!
id ID!
name String The Worker's name, or the person's handle.
urn String The Worker's URN; null for a person.

AgentTaskReference

2649 (hrn:node:hadronmemory.com:specs:cor:agt:050:01): one typed reference, as stored. The platform never resolves target.

Field Argument Type Description
kind AgentTaskReferenceKind!
target String! Stored exactly as given (at most 512 characters).
label String Optional, at most 120 characters; null when none was given.

AgentTaskRequirements

What the platform's matcher must respect when it chooses an assignee (plan design:agent-tasks section 3.1; consumed by T3).

Field Argument Type Description
roles [String!] Any one listed role suffices; null retains the single-role requirement.
teamWorkerId ID Optional matching team lead; never an authorization grant.
role String
familyIn [String!]
familyNotIn [String!]
excludeWorkerIds [ID!]
minTier String The lowest model tier the assignee may run at: low, mid or high (hrn:node:hadronmemory.com:specs:cor:agt:060:06). Null when the task names none.
modelGroupIn [String!] Model groups the assignee's model must be in at least one of (hrn:node:hadronmemory.com:specs:cor:agt:060:12). Null when the task names none.
modelGroupNotIn [String!] Model groups the assignee's model must be in none of (hrn:node:hadronmemory.com:specs:cor:agt:060:12). Null when the task names none.

AgentTaskResult

A finished task's result (hrn:node:hadronmemory.com:specs:cor:agt:050:01).

Field Argument Type Description
outcome String! One word: succeeded, failed, or a word the team chooses.
findings AgentTaskFindingPage! #2662: immutable result findings; default 20, max 200, limit 0 count-only; same readers as this result.
limit Int
offset Int
summary String
evidence String A URL or a node URN.

AgentTaskRunSettings

4291 (hrn:node:hadronmemory.com:specs:cor:agt:050:01): a task's own run settings as stored. Each field is null when the task names none.

Field Argument Type Description
family String
model String
tier String high, mid or low; null when the task names an exact model or neither.
effort EffortLevel

AgentTaskSessionEndRequest

1709 — a task's request that its assignee end its session (hrn:node:hadronmemory.com:specs:cor:agt:050:10).

Field Argument Type Description
workerId ID! #4223: the worker asked to end its session. On AgentTask.sessionEndRequest it is always the task's current worker assignee.
sessionId ID! The session asked to end: only this one is ever ended, never a later replacement.
requestedAt DateTime!
dueAt DateTime! When the App's grace runs out (default 10 minutes after the request).
resolution AgentTaskSessionEndResolution Null while open; else ENDED (the session ended), END_ISSUED (the platform issued worker.end through a live host) or NO_LIVE_HOST (nothing more happens).
resolvedAt DateTime
operationId ID The worker.end operation the platform issued (END_ISSUED).

AgentTaskSkippedCandidate

One candidate a failed match skipped (#3816): the worker and every reason, in AgentTaskMatchSkipReason order.

Field Argument Type Description
workerId ID!
name String!
reasons [AgentTaskMatchSkipReason!]!

AgentTaskStallSchedule

1706 — an App's effective stall windows, in minutes (hrn:node:hadronmemory.com:specs:cor:agt:050:14–:17).

Tunables, not contract: the platform defaults are 15, 60, 20 and 30.

Field Argument Type Description
appId ID!
notStartedMinutes Int! Not started (hrn:node:hadronmemory.com:specs:cor:agt:050:14): counted from the assignment when the task has no later start-by time.
noProgressMinutes Int! No progress (hrn:node:hadronmemory.com:specs:cor:agt:050:15). Also the escalation step for that alarm.
ownerReactionMinutes Int! Owner didn't react to a finished or cancelled child task (hrn:node:hadronmemory.com:specs:cor:agt:050:16).
assignmentMinutes Int! Couldn't be assigned (hrn:node:hadronmemory.com:specs:cor:agt:050:17).
hostLapseCheckIns Int! #1763 — how many of a host's own check-in intervals may pass without a refresh before its registration in this App lapses (hrn:node:hadronmemory.com:specs:cor:agt:070:01): 2 to 10, default 3.
sessionEndGraceMinutes Int! #1709 — how many minutes a worker asked to end its session on its task's finish or cancellation has before the platform ends it through its host (hrn:node:hadronmemory.com:specs:cor:agt:050:10): 1 to 1440, default 10.
hostReportTimeoutMinutes Int! #1881 — how many minutes a host has to report an operation it collected before the platform fails it (hrn:node:hadronmemory.com:specs:cor:agt:070:02): 5 to 1440, default 60.
updatedAt DateTime When the App last changed them; null while every window is the default.

AgentTeamAlarmSchedule

1706 — one owner in an alarm's chain, and when the alarm wakes them

(hrn:node:hadronmemory.com:specs:cor:agt:050:19). The nearest owner is woken when the alarm is raised; owner i falls due i windows later, and is woken only while the alarm is unacknowledged (hrn:node:hadronmemory.com:specs:cor:agt:050:20). This is the platform's record that the owner is due a wake-up; delivering it is the heartbeat slice's.

Field Argument Type Description
chainIndex Int! The owner's position in the chain, 0 for the nearest.
owner AgentTaskParty
dueAt DateTime!
wokenAt DateTime Null until woken; stays null on an alarm acknowledged before it fell due.

AgentTeamEvent

One append-only record of something that happened in a team App's task work (hrn:node:hadronmemory.com:specs:cor:agt:050:11). Never changed or removed; an alarm's acknowledgement is the one thing added later. payload carries ids, counts and outcome words only, never message or description text.

Field Argument Type Description
id ID!
appId ID!
type String! e.g. task.created, task.assigned, task.reassigned, task.started, task.progress, task.finished, task.cancelled, task.handed-back (#2651: its payload is the reason code only, never the reason text); the alarms stall.not-started, stall.no-progress, stall.owner-unreactive, assignment.unassignable, stall.finish-by (#2648), alarm.dark-worker (#2755: task-less, subjectWorker is the worker gone dark), alarm.coordinator-cadence (#2763: task-less, subjectWorker is the coordinator that stopped assigning); alarm.stale-sweep (#4233: task-less and workerless: a host of an App in sweep mode OBSERVE or APPLY whose last run the server recorded more than five minutes ago (the server's clock, not the host's; a switch-on of the mode restarts the clock); payload.hostId names the host, the alarm goes to the App's managers and ends when the host records its next run); availability.changed; assignment.queued, assignment.matched (the platform's assignment, hrn:node:hadronmemory.com:specs:cor:agt:060:06); host.registered, host.lost; host.operation.succeeded, host.operation.failed (hrn:node:hadronmemory.com:specs:cor:agt:070:02).
taskId ID
taskHandle String The task's stored handle (hrn:node:hadronmemory.com:specs:cor:agt:050:01, Proposed). Null when taskId is null or the task no longer exists; never invented.
actor AgentTaskParty Who acted: the Worker when the request was bound to a worker session, else the person.
actorRunId ID #1833 — the headless run that acted, when a run made this event (actor is then null: a run is never a person or a worker). Null otherwise. Matches AgentTask.createdByRunId for the task a run created.
actorAppKeyId ID #3132 — the App key that acted, when a key made this event (its claim of an outside item; actor and actorRunId are then null: a key is never a person or a worker). Null otherwise.
subjectWorker AgentTaskParty The worker the event concerns, e.g. a new assignee.
subjectUser AgentTaskParty #3132 — the person the event concerns, when a key or a run acted for one it cannot itself resolve (the assignee its claim named). Never the actor. Null otherwise.
severity AgentTeamEventSeverity ALARM for an alarm; null for an ordinary event.
chain JSON Alarms only: the owner chain when the alarm was raised, nearest first.
acknowledgedBy AgentTaskParty
acknowledgedAt DateTime
escalationEndedAt DateTime #3934 — alarms only: when this alarm's escalation ended, the earlier of its acknowledgement and its RECORDED end (hrn:node:hadronmemory.com:specs:cor:agt:050:20); null while the alarm is in effect, and on any ordinary event. The recorded end is written once, by the evaluator pass (every minute) or by the acknowledgement, from the earliest end the available history supports for any kind of alarm: it is at most one pass late and never moves once written. Until it is written the alarm reads as still in effect. Ending changes nothing on the alarm: it is not acknowledged, deleted or hidden, and an owner may still acknowledge it.
payload JSON! A dark-worker alarm's payload carries its reason (overdue, wake-unacked) and window for every reader; its evidence (lastCheckedAt, oldestWakeAgeSeconds) only for a reader of the worker's internals.
createdAt DateTime!
episodeStart DateTime #1706 — stall alarms only: when the stall episode began (hrn:node:hadronmemory.com:specs:cor:agt:050:13), the instant of the move that began the condition. One alarm per task, rule and episodeStart.
wakes [AgentTeamAlarmSchedule!] #1706 — alarms only: who the alarm wakes and when, nearest owner first (hrn:node:hadronmemory.com:specs:cor:agt:050:19). Null for an ordinary event.

AgentTeamEventsPage

3933: one page of an App's team events and whether more remain (hrn:node:hadronmemory.com:specs:cor:api:120:04).

Field Argument Type Description
events [AgentTeamEvent!]!
hasMore Boolean! True when events beyond this page match the same read.
nextCursor ID The id of the last event served when hasMore, to pass as after (or with newestFirst as before); null on the last page.

AgentTickerTemplate

2024 — one ticker an Agent declares. Casting a worker from the Agent into an App creates the worker's tickers from the live

templates and subscribes it, in the cast's own transaction. A SNAPSHOT: a later edit or removal reaches only future casts; existing workers and tickers are untouched. Identity is the id, never the name or the position. The cadence is the requested one; the cast raises it to the App's floor. Reasons are never empty.

Field Argument Type Description
tickCode String! The code future generated tickers receive, derived from this template's current name (hrn:node:hadronmemory.com:specs:cor:agt:110:01).
id ID!
agent Agent!
revision Int! Counts edits; an update or delete must name the revision it saw, and a stale one is refused with TICKER_TEMPLATE_REVISION_MISMATCH.
shapeVersion Int! The shape of this record. Only 1 exists.
name String!
cadenceSeconds Int!
quietHours JSON A timezone and weekly windows; null when none.
relevance TickerRelevance!
reasons [TickerReason!]!
createdAt DateTime!
updatedAt DateTime

AgentWebhook

Webhook trigger (D-2026-05-02). The secret is NEVER exposed here — the URL is returned once at create/rotate.

Field Argument Type Description
budgetTokens Int Optional per-run token limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
budgetActions Int Optional per-run action limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
id ID!
organizationId ID!
appId ID!
agentId ID
userId ID
scopeId ID Spec 049: the scope this trigger's runs carry (null ⇒ 'app').
name String!
argsSchema JSON
entryNodeUrn String!
eventData JSON
policy JSON
aiConfigName String
enabled Boolean!
lastCalledAt DateTime
createdAt DateTime!
createdBy String

AgentWebhookCredentials

Create/rotate result — path + platform token are shown ONCE.

Field Argument Type Description
webhook AgentWebhook!
path String! Server-relative URL path: /hooks/<secret>/<name>. Append ?hpt=<token>.
token String! The time-limited platform JWT (hpt) — the second factor. Store it now.

AgentWebhooksPage

Field Argument Type Description
items [AgentWebhook!]!
total Int!

AgentlessSessionEnd

4292: the outcome of endAgentlessSession.

Field Argument Type Description
sessionId ID!
ended Boolean! True when this call ended the session; false when it had already ended.
handoff Boolean! Whether a handoff names this session. False means no handoff was recorded.

AgentsPage

Field Argument Type Description
items [Agent!]!
total Int!

AiConfigTestKnob

1417: what one provider knob in the effective params did on the call.

Field Argument Type Description
param String! The params key, e.g. temperature.
state String! SENT (carried to the provider, no adapter warning) | ADJUSTED (sent, but the adapter changed the value, e.g. clamped to its range) | DROPPED (the adapter removed it, e.g. temperature on a reasoning model) | NOT_SENT (the platform does not forward it; see detail)
detail String Why it was not sent, or the adapter's own warning text.

AiModelPrice

046-usage-metering: effective-dated provider rate row. Prices are micro-cents (1e-8 USD) per MILLION tokens, as base-10 integer strings.

Field Argument Type Description
id ID!
provider String!
model String!
tier Int! Pricing tier 1-3; tier 1 is the default everything resolves today.
inputMicroCentsPerMTok String!
outputMicroCentsPerMTok String!
markupBasisPoints Int Per-tier debit markup in basis points (2500 = 25%). Null falls back to the CREDIT_MARKUP_PERCENT env default.
effectiveAt DateTime!
createdAt DateTime!
createdBy String

AiModelPriceList

Field Argument Type Description
items [AiModelPrice!]!
total Int!

AiProviderEndpoint

1373: one known endpoint for a provider, from the server's single suggestion list.

Field Argument Type Description
url String!
label String!
isDefault Boolean! The endpoint a config with no endpoint uses.
note String What the URL does not say: billing, terms.

AiServiceConfig

036-ai-service-config: a named AI service configuration (masked management view — never carries key material beyond the preview). Owned by exactly one of HadronServer / Organization / App / Agent. Resolution walks App -> Agent -> Org (of the App) -> HadronServer and returns the first ENABLED config with the requested name. Well-known fallback name: 'default' (conventional extras: 'fast', 'frontier'). Name is unique per owner.

Field Argument Type Description
id ID!
name String!
urn String The config's URN, computed from its owner's current URN plus its name (hrn:node:hadronmemory.com:specs:cor:urn:010:01, V60-V63): hrn:aiconf:<org>:org:<name>, hrn:aiconf:<root>:app:<app-slug>:<name>, hrn:aiconf:<author-root>:agent:<agent-slug>:<name>, or hrn:aiconf:server:<name> for a HadronServer owner. Null for a name that cannot be a URN atom (a trailing '-' or '_'), for a stored name that is not lower-case canonical, and for a validly named config of a HadronServer that is not the current one (the oldest live row). Renaming the config re-addresses it, with no alias.
ownerType AiConfigOwnerType!
ownerId ID! ID of the owning HadronServer / Organization / App / Agent.
provider String! Provider identifier; known: 'anthropic' | 'openai' | 'glm' | 'kimi' | 'bedrock' | 'openai-compatible' (any OpenAI-wire host; endpoint required).
model String! Model identifier, passed verbatim to the provider.
hasApiKey Boolean!
apiKeyPreview String Ellipsis + last 4 characters of the stored key; null when no key.
params JSON Provider-specific knobs (maxTokens, thinking, effort, baseUrl, ...).
endpoint String #1373: the base URL this config's requests are sent to, as stored. Null = the provider's default (see effectiveEndpoint and aiProviderEndpoints).
effectiveEndpoint String #1373: where a request for this config actually goes: endpoint, else the provider default. Null only for bedrock, whose endpoint is derived from its region.
apiStyle AiApiStyle #1373: the wire protocol as stored; null = the provider default. OpenAI-compatible providers only.
effectiveApiStyle AiApiStyle #1373: the wire protocol a request actually uses (apiStyle, else the provider default); null for single-protocol providers.
enabled Boolean! Disabled configs are skipped by resolution (the walk continues outward).
createdAt DateTime!
updatedAt DateTime

AiServiceConfigTestError

Field Argument Type Description
code String! NO_API_KEY | KEY_UNREADABLE (the stored key cannot be decrypted here; re-enter it) | CONFIG_INVALID (the config cannot be built at all, e.g. a malformed Bedrock key; no call made) | QUOTA_EXCEEDED (a platform-funded test with the org's daily token allowance used up; no call made) | LLM_CALL_FAILED (the provider call failed or timed out; see transient)
message String! Provider error text, scrubbed of the key and truncated.
transient Boolean!

AiServiceConfigTestResult

1378: one test call, made through the same client and endpoint a run uses.

Field Argument Type Description
ok Boolean!
provider String!
model String!
endpoint String The endpoint the request actually went to: the explicit endpoint, else the host the SDK chose (OPENAI_BASE_URL / ANTHROPIC_BASE_URL when the server sets one, Bedrock's regional host), else the catalog default. Null when it can't be known (Bedrock with no region).
apiStyle AiApiStyle The wire protocol the request actually used.
used AiServiceConfigTestUsed!
latencyMs Int!
reply String The model's reply, truncated.
error AiServiceConfigTestError
knobs [AiConfigTestKnob!]! #1417: what each provider knob in the effective params did on the call. Empty unless the call completed (a failed call's adapter warnings are unknown), or when the params carry none. maxTokens is listed as the ceiling it set (ADJUSTED when the probe's cap is lower); toolCalling (a gate) is not a provider knob and is not listed.
chat ChatProbeOutcome #4005: the chat probe's outcome. Null unless chatProbe was requested. A closed status and nothing else: no key, model text or provider text.

AiServiceConfigTestUsed

1378: per field, whether the test used the saved value or the override.

Field Argument Type Description
provider AiConfigTestValueSource!
model AiConfigTestValueSource!
endpoint AiConfigTestValueSource!
apiStyle AiConfigTestValueSource!
params AiConfigTestValueSource!
key AiConfigTestKeySource!

AiServiceConfigsPage

Field Argument Type Description
items [AiServiceConfig!]!
total Int!

App

A runtime caller identity owned by exactly one Organization or User. It owns long-lived App Keys and installs Agents through the AppAgent N:M join: one App may install many Agents, and one Agent may be installed in many Apps. The singular agentId / agent fields below are soft-deprecated convenience reads of the first install, not a direct foreign key.

Field Argument Type Description
id ID!
name String!
urn String!
availableMemberRoles [String!]! #2171 (R211): the member roles this App offers: the union over its installed Agents, primary first.
teamPausedAt DateTime #2138: when the whole team was paused (setTeamPause), or null. Separate from every worker's own pause.
sweepMode SweepMode! #4224 (S3 of #4229): the App's sweep switch (setAppSweepMode). OFF by default.
viewerManages Boolean! #2109 — whether the current caller manages this App: its owner, an owner-role member, a live ADMIN or OWNER of its organization, or a platform admin for an organization-owned App. A known fact for an App the caller can read, so false is an answer and not a refusal. False for an App key, an impersonated session, a headless run and a request bound to a worker session: this nested read names no instruction, so no worker carries its holder's right on it (hrn:node:hadronmemory.com:specs:cor:dmo:050:12). This is not permission to perform every task or worker operation: each operation checks its own authority.
properties JSON #3125 S1 (hrn:node:hadronmemory.com:specs:cor:dmo:050:02, hrn:node:hadronmemory.com:specs:cor:dmo:050:20): the App's own JSON object, written whole by whoever manages it (setAppProperties). Readable by whoever may read the App by app(ref:) (an org member, or the user-owner) and by whoever manages it; null for anyone else, an App key included, whichever field reached the App. Never put a secret here. The platform reads only the taskIntegrations key (hrn:node:hadronmemory.com:specs:cor:agt:120:01), where each team lead reads as its worker URN; every other key is the team's, returned as written. Null = no properties.
propertiesRevision Int #3125 S1: the revision setAppProperties checks expectedRevision against. 0 until the first changing write; each changing write adds 1. Null for a caller who may not read properties.
chatbotAiConfigId ID #3957 (hrn:node:hadronmemory.com:specs:cor:dmo:050:10): one of this App's OWN AI configs, used for its chats unless a chat stored its own choice. An id, never a key. Readable by an App member and by whoever manages the App; null for anyone else, and null when unset. A deleted config clears it. Set and cleared with setAppChatbotAiConfig.
defaultChannel Channel Spec 049 Phase 4: the App's default Channel — the row its team chat became (null until provisioned).
policy JSON App-layer action-policy link (hrn:node:hadronmemory.com:specs:cor:acl:040:02, #510). Null = no restriction. Set at createApp and changed or cleared with updateApp(policy:), under updateApp's own gate: an org ADMIN (or a platform ADMIN) for an org-owned App, the owner for a user-owned App (#3423).
organizationId String
organization Organization The owning Organization when the caller may read that Organization; an App read alone does not grant it.
agentId ID SOFT-DEPRECATED convenience read: the FIRST installed Agent. An App installs MANY Agents through the `AppAgent` join (023-app-shape Phase 2b, which DROPPED the direct FK that 008-agent-installation had introduced) — see `appAgents` below for the real cardinality. Kept so single-Agent clients keep working; do not build new multi-Agent logic on it. `agentId` and `agent` name the PRIMARY install's Agent and answer as that Agent's own read does: both are null when the caller may not read it, even when a later install is readable. Null is not proof that nothing is installed; `appAgents` lists every install, an entry whose `agent` is null being an installed Agent withheld from this caller. A caller who reaches a user-owned App only as an owner-role member gets null on both for a different reason: WITHHELD (#2089). Render it as unknown.
agent Agent
installedAgentUrn String SOFT-DEPRECATED convenience read: the FIRST installed Agent's canonical URN, matching agentId / agent. Use appAgents for the full install roster. null can also mean WITHHELD from this caller (#2089), not only "none". An installed agent stays AUTHOR-ROOTED forever, so this is simply that Agent's own URN: hrn:agent:<author-org>:<agent-slug>. Two orgs installing same-slug agents from different authors therefore still produce distinct URNs (they differ at the author root), enabling audit-log entries to identify the selected Agent unambiguously without a PK disambiguator. The v1 spec-021 R2 install chain (hrn:agent:<installing-org>::<app-slug>::<author-org>:<agent-slug>) is RETIRED — see #697 Stage 2 / D10 and emitInstalledAgentUrnV2. Returns null when the App has no installed Agent or the selected Agent's stored URN cannot be emitted in grammar v2, or when the caller may not read that Agent (it answers as `agent` does).
trainingMode Boolean!
surfaces [String!]!
members [AppMember!] The App's members. null means WITHHELD from this caller (#2089): a user-owned App's owner-role member reaches the App record but not its roster. Never read null as an empty roster. The App's owning user, and callers of an org-owned App, get the real list (a real empty list included).
memberCount Int Member count. null means WITHHELD from this caller (#2089), never zero; the real count (a real 0 included) for callers who may see the roster.
sharedMemory Memory The App's SHARED app-class memory (#965) — the team space the shared/team chat and the worklog live in, provisioned at install since #951. This is the App → memory hop clients need to default a team-memory argument (hadron-cli#399) instead of scanning every readable memory for Memory.appId. Read-only resolution, never provisions: the memory holding the App's 'worklog' root wins (the ledger home — oldest, mirroring the worklog locator), else the oldest agent-keyed shared row (sharedMemoryOfAgentId set; Worker working memories are also app-class rows under this App and are never this answer). Null when nothing has provisioned a shared memory yet (an App predating #951 with no team activity), or when the caller cannot read the memory record (the ordinary record read gate — denied and missing are indistinguishable).
appType AppType!
role AppMembershipRole!
description String
agentTools [String!]!
aiProvider String null can mean WITHHELD from this caller (#2089), not only that it is not configured.
aiModel String null can mean WITHHELD from this caller (#2089), not only that it is not configured.
hasAiApiKey Boolean Whether an AI API key is configured for this App. null means WITHHELD from this caller (#2089): only the owning user of a user-owned App holds its AI configuration. Never read null as false; a real false means no key.
expiresAt DateTime
createUserPermission CreateUserPermission!
identifyUserMethod IdentifyUserMethod!
sessionTimeoutSeconds Int!
sessionDormancyDays Int! Ruling DY-5: days without activity after which a lapsed worker session of this App is DORMANT. No agent act (post, read, mark-read) resumes a dormant session; only an explicit rebind by its human holder brings the worker back, and the router stops routing it. Default 90.
agentSessionsExpire Boolean! Ruling DY-3: whether startAgentSession stamps a hard expiry by default. False means this App's agent sessions have no hard expiry unless the call passes sessionTimeoutSeconds (still capped by the App's ceiling).
anonymousTtlDays Int!
appAgents [AppAgent!] Agents installed in this App, by a physical row or derived from a direct import of a physically installed Agent (#2168). Derived installations do not write an AppAgent row. One App credential routes to all of them via the URN supplied in the request. null means WITHHELD from this caller (#2089): a user-owned App's owner-role member does not see its installation roster. Never read null as no installed Agents.
agents [Agent!] 023-app-shape: convenience list of the installed Agents this caller may read: the non-null Agent entries of `appAgents`. A withheld install is omitted here and appears in `appAgents` with `agent: null`. Only the installed Agents this caller may read: the list may be PARTIAL, an unreadable Agent is left out, and its length is not the install count (use `appAgents`, one entry per install). Order matches the readable non-null entries of `appAgents`: served installation creation time, then Agent id. When any installed Agent is withheld, every entry shares the App date, so order is by id. null means WITHHELD from this caller (#2089), never no Agents.
keys [AppKey!]! Key inventory, only for whoever manages the App as themselves, never through a worker session, instructed or not: a nested field carries no instruction, so an instructed worker lists through appKeys / appKeysPage (hrn:node:hadronmemory.com:specs:cor:dmo:050:05; hrn:node:hadronmemory.com:specs:cor:dmo:050:12 S6).
createdAt DateTime!
updatedAt DateTime

AppAIConfig

Decrypted AI config for an App (owner / org admin only).

Field Argument Type Description
provider String!
apiKey String!
model String!

AppAgent

023-app-shape US1: the App↔Agent N:M join. Reintroduced after spec 008 collapsed it; per FR-003 it carries NO role column (system memory is read-only to every App) and per FR-001 it carries NO trainingMode column (training mode is per-App, on App.trainingMode).

Field Argument Type Description
app App The App when this caller may read it; strict user ownership still applies.
agent Agent The installed Agent when this caller may read its definition; an installation license alone does not grant that read.
bootPromptRef String #2045 — the canonical URN of the compiled boot prompt the install's pointer names now (a moved node shows its new URN; a hard-deleted one its URN at write time). Null when no pointer is set OR when the caller may not see it (the App's participants only): null is not proof that no pointer exists.
bootPromptTargetDeleted Boolean #2045 — whether the pointer's target is deleted (soft or hard): true / false, and null when no pointer is set or the caller may not see it. Same gate as bootPromptRef. Nothing is served from a deleted target (R27).
bootPromptServe BootPromptServeOutcome #2708 — what a non-customised worker of this App, or a chatbot chat in it, would be served now (hrn:node:hadronmemory.com:specs:cor:agt:040:10): the install's pointer, else the Agent's. Computed by the resolver a bind uses, so it never substitutes a fallback. Null when the caller may not see it (same gate as bootPromptRef, the App's participants), which is judged before anything is resolved.
installMethod InstallMethod #3435 (hrn:node:hadronmemory.com:specs:cor:dmo:050:03, :050:06, :050:11) — how this App installs the Agent: ROW (an AppAgent row) or DERIVED (a direct import of an Agent installed here, no row). Answered only on App.appAgents, and only when the caller may read EVERY Agent installed in the App, row installs and derived ones alike. Otherwise it is null on EVERY entry, ROW ones included: a per-entry answer would show, by elimination, which installs derive from an Agent the caller cannot read (that the App runs one, and never which). Null is therefore not proof of anything, and also what an AppAgent reached through another field returns. createdAt (below) follows the same gate.
importer Agent #3435 — the installed Agent this DERIVED install derives from: the importer that gives its createdAt. Null for a ROW entry and whenever installMethod is null (same whole-App read gate), so a DERIVED entry always has a readable importer.
createdAt DateTime! When every installed Agent is readable: physical row creation time, or the computed earliest install/import witness time for a derived entry. Otherwise every entry shares the App creation time. The newly created install mutation payload retains its real row time. App.appAgents sorts by the served time, then Agent id.
createdBy String Row audit fields are visible only when the caller may read EVERY installed Agent in this App. Otherwise all three are null on EVERY entry, including physical rows. A derived entry has no row audit identity, so these stay null even under the whole-App gate; importer identities are never copied.
updatedAt DateTime
updatedBy String

AppCreated

Returned once at App creation / regenerateAppKey — the raw key is never stored

Field Argument Type Description
app App!
rawKey String!

AppDeliverySettings

Delivery timing per App. Busy/stuck bounds and relation are Proposed (hrn:node:hadronmemory.com:specs:cor:agt:080:05).

Field Argument Type Description
batchWindowSeconds Int! The existing ticker cadence floor and wake-rate ceiling, also the batching window. Changing it affects ticker cadence. DEPRECATED (#2138): push batching is superseded by channel checks; kept readable, no new consumer.
busyDelaySeconds Int! Whole seconds, 1..86400; default 600. DEPRECATED (#2138): superseded by channel checks.
stuckWindowSeconds Int! Whole seconds, 1..604800; default 900. Must exceed busy delay plus batch window. DEPRECATED (#2138): superseded by channel checks.
checkPeriodSeconds Int! #2138: a worker with a task is expected to check its team channel every period. Whole seconds, 60..86400; default 600. Set together with the team ticker's cadence.
failedChecksToOverdue Int! #2138: a worker with a task is OVERDUE after this many missed periods plus 5 minutes. Whole number, 1..100; default 2.
darkAlarmWindowSeconds Int! #2755: a worker's due wake left unacknowledged this long raises the dark-worker alarm. Whole seconds, 300..86400; default 1800. Independent of stuckWindowSeconds.

AppGrant

1747 — a narrow, named permission held by one worker (hrn:node:hadronmemory.com:specs:cor:agt:080:24).

Field Argument Type Description
id ID!
app App!
worker Worker!
name AppGrantName!
grantedAt DateTime!
revokedAt DateTime

AppKey

Field Argument Type Description
id ID!
appId String!
keyPreview String!
label String
createdAt DateTime!
lastUsedAt DateTime
revokedAt DateTime
scopes [AppKeyScope!]! #1749 — the scopes this key holds now (hrn:node:hadronmemory.com:specs:cor:aut:010:03). Whoever manages the App only.
hostUses [HostKeyUse!]! #1709 — what this key did as a host, newest first (hrn:node:hadronmemory.com:specs:cor:agt:070:07: every use is recorded). Whoever manages the App only.
first Int

AppKeyCreated

Returned once at creation — the raw key is never stored

Field Argument Type Description
key AppKey!
rawKey String!

AppKeyPage

2213 — one page of an App's live keys.

Field Argument Type Description
items [AppKey!]!
total Int!
hasMore Boolean!

AppKeyScope

1749 — a scope an App key holds. A closed list: attention:deliver, and (#1709) host:operate.

Field Argument Type Description
scope String!
grantedAt DateTime!
grantedBy ID!
hostId String #1709 — the one host a host:operate scope is bound to (hrn:node:hadronmemory.com:specs:cor:agt:070:04); null for every other scope.

AppMember

Field Argument Type Description
appId ID!
userId ID!
app App The App when the caller may read it; an external App member can still see their membership row.
user User!
role String!
isOrgExternal Boolean! 023-app-shape US2: true when this User is an AppMember of the App but NOT an OrgMember of the App's owning Organization. Derived at query time from the absence of an OrgMember row (per spec 023 FR-011 — no appOnly column is added to the AppMember table). Unlocks the B2C / therapy / consumer use cases where end-users use an App without joining the operator's org.
createdAt DateTime!
updatedAt DateTime

AppMemorySource

2190: one reason a memory is in an App's scope.

Field Argument Type Description
kind AppMemorySourceKind!
agentId ID The installed or base Agent, for AGENT_SYSTEM, AGENT_LINK and INHERITED_BASE; null for TEAM_SPACE and APP_MEMORY. An id only: when it does not resolve to an Agent this caller may read, show the source kind without a name.

AppMemoryWriteGrant

2484: an App's write grant on one memory under one loc prefix, for the App's userless runs only. It permits node create and update at the prefix and its colon-boundary descendants, checked live at each write; never delete, edges, memory settings or stored files, and nothing for another App's run, a user-backed run, an App key or a worker. A revoked grant stays as a terminal row. hrn:node:hadronmemory.com:specs:cor:agt:010:01

Field Argument Type Description
id ID!
appId ID!
memoryUrn String The granted memory. Null when the grant is on someone's personal or private memory and the caller is not its owner.
prefix String! The loc prefix: the loc itself and its colon-boundary descendants (reports:team-progress does not cover reports:team-progressX).
registerNodeUrn String The register line this grant cites. A citation only, never evidence that the line exists.
grantedBy String! The person who set it.
createdAt DateTime!
revokedAt DateTime
revokedBy String
notEffective Boolean True when this live grant can no longer take effect because its target memory is no longer one a write grant may target (for example an Agent system memory, or one later encrypted): the row is accurate but authorizes nothing, and only a revoke clears it. Derived at read by the same function the write doors call, never stored, and gone when the memory qualifies again. False on a revoked row and on an effective one. Null when memoryUrn is null (the memory is concealed from the caller). hrn:node:hadronmemory.com:specs:cor:agt:010:01
notEffectiveReason String Why notEffective is true: system, encrypted, install-memory, no-owner or tenancy; null otherwise, and null whenever memoryUrn is null. Display only: a client must not branch on a value it does not know.

AppRun

One headless run — the audit record AND (v1) the activation: policy snapshot, live budgets (zeroing halts the run), lifecycle, trigger provenance. Spec hrn:node:hadronmemory.com:specs:cor:agt:010:02.

Field Argument Type Description
id ID!
urn String Computed grammar-v2 URN hrn:apprun:<root>:<app>:<run-id> (#696). Null for the rare multi-segment App URN the flat shape cannot express.
organizationId ID!
appId ID!
agentId ID
userId ID On-behalf-of user (cor:agt:010:01). Null = pure App service identity.
triggerKind AppRunTriggerKind!
triggerId ID
entryNodeUrn String!
eventData JSON
data JSON The run envelope (plan-multi-node D-MN-1): fields extracted by flow nodes as the walker advances. eventData stays the immutable trigger payload; on key collision the envelope wins.
hops JSON Per-hop trail (#538): one element per completed hop — [{node, edgeOut, startedAt, finishedAt, tokensSpent}]. edgeOut is the routing edge taken FROM the hop (null on the last). A hop that failed mid-execution has no element; curNodeUrn + failure identify it.
spawn JSON Fan-out state (plan-spawn, #548): set on runs that called hadron_spawn — {processItem, itemKey, callback?, itemCallback?, total, callbackFiredAt?, callbackError?}. callbackError records a callback mint that was denied (quota/policy) — the digest that never came.
policy JSON
budgetTokens Int Remaining LLM-token budget — live-decremented; zero halts the run.
budgetActions Int Remaining action budget — live-decremented per write/tool action.
tokensSpent Int Total LLM tokens consumed by this run (#832). Unclamped, so it stays truthful when a hop overshoots the remaining budget — unlike budgetTokensInitial minus budgetTokens, whose decrement is clamped. Counts every hop whose LLM call COMPLETED, including hops whose run later failed — strictly more than a sum over the hops trail, which has no element for a hop that did not complete. A tool-loop call that is REJECTED (a provider or transport error, a tool denied by policy, a handler that threw, hadron_fail) counts the steps the SDK had already completed, once: the provider billed them. Usage the SDK did not report is not counted: the step that failed, and any completed step without token counts. Such a run can still under-report. A rejection before any step completed counts nothing, and unknown is never recorded as zero. Do not treat this as a billing figure. NULL means UNKNOWN: a run minted before the counter existed, with no hop trail to back-fill from. 0 means it genuinely spent nothing.
actionsSpent Int Total budgeted actions consumed (#832) — only actions actually admitted by the budget guard; a denied action counts nothing. NULL means UNKNOWN, not zero: runs minted before the counter existed have no recorded action spend and, unlike tokens, no hop-trail signal to reconstruct one from. Reporting 0 would contradict their already-decremented budgetActions.
costMicroCents String Priced LLM cost of this run in micro-cents (1e-8 USD), as a string (#2439): the sum of its usage events' cost. Events with no known price add nothing. NULL means UNKNOWN (a run minted before the counter existed), not zero.
failureReason AppRunFailureReason A failed run's cause in plain words (#2439): what happened, who can fix it and where. Null when the run has no failure. Static text derived from the failure and the run's budgets; it names no memory, id or tool, so it discloses nothing the caller does not already read. The raw failure stays available on the failure field.
scope SearchScopeInfo Spec 049 (D-2026-09-13-004): the scope this run carries, as YOU may read it — the snapshot taken at mint (the trigger's scope, or a spawned parent's) re-intersected with your access; memoryUrns lists what you may read of it and droppedCount the rest. Null ⇒ the run carries no named scope and its view is the App's attached memories ('app').
register [RegisterViewRow!]! Spec 049 Phase 6 (D-2026-09-13-007): the register this run's attendee (its Agent in its App) carried at mint, as YOU may act on it — rows from the snapshot, watermarks live, gates evaluated now. Empty when the run has no Agent (no attendee) or no rows.
budgetTokensInitial Int The token budget this run was MINTED with — budgetTokens is what REMAINS. NULL for runs minted before this was recorded, which is deliberate: 0 would render as 'no budget' rather than 'unknown'.
budgetActionsInitial Int The action budget this run was minted with (#832). NULL for pre-existing runs.
status AppRunStatus!
curNodeUrn String
parentRunId ID
failure JSON
timeoutMs Int
attempts Int!
startedAt DateTime
finishedAt DateTime
createdAt DateTime!
createdBy String
app App The App this run activated. Null when the caller may not read that App, or when the App row was hard-deleted. appId remains the audit record.
agent Agent The agent that ran, when the run resolved one and the caller may read it.
user User On-behalf-of user (cor:agt:010:01). Null = pure App service identity. Personal fields on the returned User carry their own #384 gate.
entryNode Node The resolved entry node. NULLABLE by design — entryNodeUrn is the immutable audit record and the node may have been deleted, moved, or be unreadable to this caller since the run. A null here is a normal, expected state.
servedPrompt ServedPrompt #2047 / hrn:node:hadronmemory.com:specs:cor:agt:040:03: the boot prompt this run was served. Readable by whoever may read the run; null for anyone else.

AppRunFailureReason

Field Argument Type Description
kind String! Stable category: NOT_ADOPTED, MEMORY_UNREADABLE, CHANGED, OVER_BUDGET, POLICY_DENIED, NO_AI_CONFIG, TIMED_OUT, CANCELLED or OTHER.
summary String! What happened, in plain words.
whoCanFix String! Who can fix it.
nextStep String! What to do, and where.

AppRunsPage

Field Argument Type Description
items [AppRun!]!
total Int!

AppScopedMemory

2190 (hrn:node:hadronmemory.com:specs:cor:dmo:050:17): one memory in an App's scope. A leaf: no nested Memory or Agent.

Field Argument Type Description
memoryId ID!
memoryUrn String!
name String!
class MemoryClass!
sources [AppMemorySource!]! Every reason this memory is in scope. Never empty. Ordered by kind (AGENT_SYSTEM, AGENT_LINK, INHERITED_BASE, TEAM_SPACE, APP_MEMORY), then by agent install order.
viewerCanWrite Boolean! Advisory: whether this caller, in this request's context, may create a node in this memory (the createNode gate). Memory-level only: it never makes an inherited node editable, and every write is still decided by the server. Offer a row as an upload or new-node target only when viewerCanWrite is true AND at least one of its sources has a kind other than INHERITED_BASE. A memory present only as an inherited base belongs to the base Agent, and other Apps read it too.

AppScopedMemoryPage

2190: one page of an App's memory scope.

Field Argument Type Description
items [AppScopedMemory!]!
total Int! Size of the caller's whole scope, so a client knows when it has every page.

AppSweepMode

4224: the App's sweep mode after setAppSweepMode.

Field Argument Type Description
sweepMode SweepMode!

AppTickerSettings

1747 — an App ticker settings (hrn:node:hadronmemory.com:specs:cor:agt:080:05).

Field Argument Type Description
minCadenceSeconds Int!
selfSubscribeCadenceSeconds Int!
liveCap Int!
dailyWakeBudget Int!
dailyWakeBudgetDerived Boolean! True when the budget is derived from the roster rather than set.

AppliedTickerTemplate

2096 — a template as the apply operation reports it: its id and name only. Deliberately NOT AgentTickerTemplate:

that type's agent field default-resolves the whole Agent, and whoever manages an App need not be able to read the Agent it installed (the same reason ReleasedFromUser is not User, hrn:node:hadronmemory.com:specs:cor:acl:110:01).

Field Argument Type Description
id ID!
name String!

AppliedTickerTemplateTicker

2096 — one ticker an apply created, with the template it came from and its effective cadence (the App's floor may have raised it, R92).

Field Argument Type Description
ticker Ticker!
template AppliedTickerTemplate!
effectiveCadenceSeconds Int!

ApplyAgentTickerTemplatesResult

2096 — what applyAgentTickerTemplates did: what it created, and the templates the worker already had (a second call is a visible no-op).

Field Argument Type Description
created [AppliedTickerTemplateTicker!]!
alreadyPresent [AppliedTickerTemplate!]!

ApproveMemoryNodesResult

1591 — the outcome of approving every node of a memory.

Field Argument Type Description
approvedCount Int!
approved [NodeApprovalReceipt!]! Nodes newly approved by this call, ordered by loc.
alreadyApprovedCount Int! Nodes whose current revision was already approved (left unchanged).
skippedPlaceholders [String!]! Locs of reserved placeholders, which have no spec to approve yet.
skippedDecisionCount Int! #1641 — decisions and decision logs in this memory, which bulk approval never approves: a decision is approved individually by one of its deciders.
skippedDecisions [String!]! #1641 — the first 50 of those, by loc.
skippedBootPromptCount Int! #2043 — boot prompts in this Agent system or App install memory that this caller may not approve: only the Agent's or App's manager approves them, as themselves, never through a worker session.
skippedBootPrompts [String!]! #2043 — the first 50 of those, by loc.
unresolvedFeedback [UnresolvedFeedback!]! #1607 — unminted nodes of this memory with open discussion: a warning, never a blocker (hrn:node:hadronmemory.com:specs:cor:dmo:110:07). Ordered by loc.

AppsPage

Field Argument Type Description
items [App!]!
total Int!

Asset

Field Argument Type Description
id ID!
memoryId ID!
filename String!
mimeType String!
sizeBytes Int!
scanStatus AssetScanStatus!
scanSignature String Engine signature name recorded when the scan verdict was BLOCKED (the row is kept as an audit tombstone; its bytes are deleted). Null otherwise.
description String
uploadedAt DateTime!
uploadedBy ID Uploader (User id). Null when the asset was created server-side by an app run (hadron_store_file).
deletedAt DateTime
urn String! The asset's URN, grammar v2 (cor:urn:010:01): hrn:asset:<root>:<mem...>:assets:<asset.id>, emitted by emitAssetUrnV2 from the holding memory's STORED urn. <mem...> is one or more atoms, not always one. A per-user memory urn minted before the #697 Stage-3 flip is still compound (<root>:<agent>:app-user:<id> and friends), and each extra memory atom lengthens the asset URN with it — so the 'assets' marker is not at a fixed offset. A parser recovering the holding memory must take everything between the type word and that marker, never a fixed two-atom prefix. Prefer locating the LAST 'assets' atom and reading the id after it (assetIdFromRef does exactly this). Two degraded shapes a parser must tolerate, both of which really occur: * hrn:asset:unknown:assets:<asset.id> — the holding memory row could not be loaded. Carries no memory identity at all. * <memory.urn>:assets:<asset.id> — the pre-#697 shape, with NO hrn:asset: prefix, served when v2 emission throws (empty, over-length or charset-invalid atom in the stored memory urn). It interpolates the stored memory urn verbatim, which is normally bare (<root>:<slug>), so this shape usually looks like acme.com:docs:assets:<id>. A third oddity is reachable through the NORMAL branch, not a fallback: a legacy memories.urn row that predates the chk_memory_urn_not_prefixed guardrail can still hold a rendered hrn:mem:-prefixed value, and that composes into hrn:asset:hrn:mem:<root>:<slug>:assets:<id>. A prefix strip that assumes one leading type word will mis-read it.
publicUrl String Stable, UNAUTHENTICATED hotlink to the bytes (GET /assets/<id>). Anyone with this URL can fetch the file — there is no read gate on it. A deliberate, temporary posture; see src/api/assetPublic.ts. Do not present it in a UI as though it were access-controlled. Null unless the asset would be served right now: its per-asset switch (publicLinkEnabled) is on, the deployment switch is on, and it is CLEAN in a live unencrypted memory. Also null when the server has no BASE_URL configured (no canonical origin to build an absolute URL from) even though it would be served, so null is NEVER proof the switch is off.
publicLinkEnabled Boolean! #1667 — the per-asset public-link opt-in. STORED POLICY, not proof of publication: the anonymous link also needs the deployment switch (publicLinkAvailable) and a live, CLEAN asset in an unencrypted memory. Every asset starts false. Reading it grants no Asset read right.
canManagePublicLink Boolean! Whether THE CALLER may switch this asset's public link right now: the memory's manager under the shared class-manager predicate, never a mere writer, and strictly the owner in a personal or private memory. False in a session's memory and in an encrypted memory. Not a download capability.
publicLinkAvailable Boolean! Whether this deployment serves public links at all (ASSET_PUBLIC_HOTLINK_ENABLED). Independent of the stored opt-in, of who is asking, of the scan state and of whether a canonical origin is configured. Hide the switch when false; never infer this from publicUrl.

AssetDownloadUrl

Field Argument Type Description
url String!
expiresAt DateTime!
filename String!
mimeType String!
sizeBytes Int!

AssetListResult

Field Argument Type Description
assets [Asset!]!
total Int!
hasMore Boolean!

AssetPutHeader

Field Argument Type Description
name String!
value String!

AssetsPage

Uniform find-many envelope for assets (spec cor:api:120).

Field Argument Type Description
items [Asset!]!
total Int!

AuthContext

The resolved principal for the credential presented on THIS request (issue #562). Exposes the AuthContext the server already resolves per request (cor:aut:020:02) read-only, so any surface (CLI, portal) can validate a token and name the exact credential without per-client hacks.

Security posture (held deliberately): - Current-request only. There is intentionally no query that takes an arbitrary token as an argument — that would be a token oracle. The caller must possess the credential, exactly as today. - No reason-leak. A credential that does not resolve yields a null authContext (Query field), identically for revoked / never-existed / malformed. Once a credential HAS resolved (you authenticated as it), surfacing active-vs-revoked via apiKey.revokedAt is fine.

Field Argument Type Description
principalType PrincipalType! Which kind of credential authenticated this request.
user User The authenticated User — populated for USER principals (JWT or hdr_user_ key), null for App keys.
appId ID App.id — populated for APP principals (hdr_app_ key).
agentId ID Reserved for a future agent-credential principal; always null today.
apiKey UserApiKey The specific UserApiKey presented — populated only when the request authenticated via an hdr_user_ key (its id, label, keyPreview, createdAt, lastUsedAt, revokedAt). Null for JWT sessions and App keys.
impersonation ImpersonationInfo Set when the credential is an impersonation token: this request runs READ-ONLY as the target user, scoped to one org. Null for every other credential. Portal and CLI read this to render the acting-as state.

AutomationApproval

2441: what an adopter reviews before approving. depth carries only what previewAutomation returns to the same caller, plus the registered resources with URL userinfo and query removed.

Field Argument Type Description
state AutomationAdoptionState!
hash String!
summary AutomationSummary!
depth JSON!
readGrants [AutomationReadGrant!]! #2883: the live read grants this automation holds (memory and loc prefix), so the adopter approves what it may read. memoryUrn is null when the adopter cannot read that memory.

AutomationApprovalOmission

Field Argument Type Description
triggerKind AutomationTriggerKind!
reason String!

AutomationApprovalPage

Field Argument Type Description
rows [AutomationApprovalRow!]!
nextCursor String
omitted [AutomationApprovalOmission!]!

AutomationApprovalRow

Field Argument Type Description
triggerKind AutomationTriggerKind!
triggerRef String!
name String!
state AutomationAdoptionState!
headline String!

AutomationFlowSummary

2441: one flow of an automation (the entry flow or a flow it routes to).

Field Argument Type Description
urn String!
name String!
tools [String!]!
writes [String!]!

AutomationReadGrant

2883: an automation's READ grant on one memory (the whole memory, or one loc prefix), held on the trigger row (a schedule or webhook) a run executes. Read-only: consulted only by the run's own node read, live at each read, never for writes, listing or search, and only for the memory's own run. It carries over an edit and a re-adoption and ends on revoke or when the trigger is deleted. Runs the trigger starts carry it; a manual run does not. hrn:node:hadronmemory.com:specs:cor:agt:010:01

Field Argument Type Description
id ID!
appId ID!
triggerKind String! SCHEDULE or WEBHOOK.
triggerId ID! The AgentSchedule or AgentWebhook id.
memoryUrn String
prefix String The loc prefix (the loc itself and its colon-boundary descendants), or null for the whole memory.
grantedBy String! The person who gave it.
createdAt DateTime!
revokedAt DateTime
revokedBy String

AutomationSummary

2441: plain-language facts derived from the previewed automation. A fact the pin cannot show says not stated; nothing here is a maximum the approval enforces.

Field Argument Type Description
name String!
flows [AutomationFlowSummary!]!
reads [String!]!
writes [String!]!
tools [String!]!
schedule String
limits [String!]!
cannotDo [String!]!

AutomationTeamSnapshotGrant

3350: automation team snapshot grant history. Revocation is terminal.

Field Argument Type Description
id ID!
appId ID!
triggerKind String!
triggerId ID!
grantedBy ID!
createdAt DateTime!
revokedAt DateTime
revokedBy ID

AutomationTeamSnapshotGrantPage

3350: terminal per-automation read-only team snapshot grant; no App-wide permission. hrn:node:hadronmemory.com:specs:cor:agt:050:23

Field Argument Type Description
items [AutomationTeamSnapshotGrant!]!
total Int!
hasMore Boolean!

BeginAssetUploadResult

Field Argument Type Description
uploadId ID!
putUrl String!
putHeaders [AssetPutHeader!]!
expiresAt DateTime!
storageKey String!
maxSizeBytes Int!
allowedMimeType String!

BootPromptServeDecision

2708 / hrn:node:hadronmemory.com:specs:cor:agt:040:10: the revision a serve would be given now. The identity fields a

ServedPrompt record carries after the serve, so the two can be compared; never the text.

Field Argument Type Description
pointerLevel ServedPromptPointerLevel!
compiledNodeId ID!
servedRevSeq Int! Node.revSeq of the revision that would be served: the compiled node's newest approved revision.
provenanceRevSeq Int! The compile revision that owns that revision's provenance.
compiledContentHash String!

BootPromptServeOutcome

2708 / hrn:node:hadronmemory.com:specs:cor:agt:040:10: what a serve would decide now, from the resolver the serve

itself uses, so the same resolution rules apply. A preview of the current state: a later serve gives the same answer only while that state is unchanged (a pointer edit or an approval in between can change it). Exactly one of served and refusal is set; nothing is ever substituted for a refused serve.

Field Argument Type Description
served BootPromptServeDecision The revision that would be served; null exactly when refusal is set.
refusal BootPromptServeRefusal The typed code the serve would be refused with; null exactly when served is set.

BootPromptSigningPreview

2973 PR2 / hrn:node:hadronmemory.com:specs:cor:agt:040:09: the preview shown BEFORE an organisation's switch goes on,

one page of it. Each request mints its own previewToken over the FULL preview (every row, every page) at one consistent snapshot; any page's token is accepted within its own ten minutes. setOrgBootPromptSigning(required: true) must present it. The token grants no authority and holds no prompt text; it expires after ten minutes. While the deployment does not ship signing the rows still say what WOULD change, and enforced says false.

Field Argument Type Description
enforced Boolean!
deploymentSigns Boolean!
total Int! The number of rows across all pages.
rows [BootPromptSigningPreviewRow!]!
hasMore Boolean!
endCursor String Pass as after to read the next page; null on an empty page.
previewToken String!

BootPromptSigningPreviewRow

2973 PR2: one served compiled boot prompt the switch would change. workerId is null on the install-level row (an uncustomised worker and a chat share it).

Field Argument Type Description
appId ID!
appUrn String! Canonical v2 URN of this row's App (#4061), like agentUrn and workerUrn; a stored form that cannot be emitted is served as stored. hrn:node:hadronmemory.com:specs:cor:urn:010:01
agentId ID!
agentName String!
agentUrn String Canonical URN of this row's Agent, rooted at its author rather than the serving App; null when it cannot be derived. hrn:node:hadronmemory.com:specs:cor:urn:010:01
workerId ID
workerName String
workerUrn String Canonical URN of this row's Worker, using its stored slug; null on an install-level row or when it cannot be derived. hrn:node:hadronmemory.com:specs:cor:dmo:050:11
compiledNodeId ID!
compiledNodeUrn String
servedRevSeq Int! The revision served today.
state BootPromptSigningPreviewState!
changesToRevSeq Int

CalendarAttendee

Field Argument Type Description
name String
address String!
optional Boolean!
response CalendarEventResponse!

CalendarEvent

Field Argument Type Description
id ID!
calendarId String!
title String
description String
location String
start CalendarEventTime!
end CalendarEventTime!
isAllDay Boolean!
status String! confirmed, tentative, or cancelled (provider-neutral vocabulary).
organizer CalendarPerson
isOrganizer Boolean! True when the connected account organized the event.
attendees [CalendarAttendee!]!
myResponse CalendarEventResponse The connected account's own response; null when it is not an attendee.
webLink String
seriesId ID Series id when this is an instance of a recurring event.
createdAt DateTime
updatedAt DateTime

CalendarEventTime

An event boundary: exactly one of dateTime (timed, with timeZone) or date (YYYY-MM-DD, all-day) is set.

Field Argument Type Description
dateTime DateTime Instant for a timed event. Exactly one of dateTime / date is set.
date String Calendar date for an all-day event, as YYYY-MM-DD. Deliberately String and NOT DateTime (#205): an all-day event has no instant, and widening it to a timestamp would force a timezone the provider never supplied.
timeZone String

CalendarInfo

One calendar the connected account can see.

Field Argument Type Description
id ID!
name String!
description String
timeZone String
isPrimary Boolean! True for the account's primary calendar (the default calendarId).
canEdit Boolean! True when the connected account may create/modify events here.

CalendarPerson

Field Argument Type Description
name String
address String

CancelWebPollPayload

Result of cancelWebPoll. alreadyCancelled is true when the watch had been stopped before this call.

Field Argument Type Description
jobId ID!
cancelled Boolean!
alreadyCancelled Boolean!

CastPreviewTicker

2024 — one ticker a cast would create from an Agent ticker template.

Field Argument Type Description
name String! The generated name: the template name, a middle dot, then the worker name.
templateId ID!
templateRevision Int!
requestedCadenceSeconds Int! What the template asks for.
effectiveCadenceSeconds Int! What the ticker gets: the larger of the requested cadence and the App's floor.
relevance TickerRelevance!
reasons [TickerReason!]!

CastWorkerPreview

What castWorker WOULD do (#964) — an unsaved projection, deliberately not a Worker (no fake id to mistake for a real row). Scalars only: the ids/names here are attribution-level facts the mint-gate audience already sees, so no nested entity hands out its field resolvers.

Field Argument Type Description
teamPlacement WorkerTeamPlacement!
reportsToWorkerId ID
name String! The name the cast would take — the caller's, checked free against the App's FULL roster (retired names stay taken). Required since #1050; a nameless preview refuses exactly where the cast would.
role String The casting's role: the agent's personaRole (it cannot be overridden, R222).
agentId ID! The role-agent the casting would bind.
agentName String!
prompt String The boot prompt a bind of this casting would be served now, with the name and role filled — reviewable BEFORE the name is permanent. Null when no prompt can be served yet (no worker pointer exists before the cast).
hasNamePlaceholder ⚠️ Boolean Always null. The name-placeholder check was retired with the old variable logic (#2049).

⚠️ DEPRECATED

Retired (#2049); always null.
tickers [CastPreviewTicker!]! #2024 — the tickers this cast would create, each at its effective cadence (the larger of the template's and the App's floor). Non-reserving: nothing is written or held, so a later cast may differ if the App changes. Empty when the Agent declares none.

Channel

A CHANNEL (spec 049, D-2026-09-13-006): a durable, ordered message stream hosted in ONE memory at ONE reserved address, server-ordered and server-attributed — a platform entity, created one-to-one with its chat root. Creating it RESERVES and PROTECTS the address: generic node writes under it are refused (LOC_PROTECTED); its own operations (createTeamChatMessage, which the CLI reaches as hadron team chat post) are the only writers. The audience is the host memory's (cor:acl:030:01) — a Channel has no access layer of its own. lastSeq / lastMessageAt are the platform-maintained watermark.

Field Argument Type Description
id ID!
memoryId ID! Host memory.
memory Memory #2509: this memory's record, exactly as Query.memory answers it to the caller, or null when the caller may not read that record (or it is deleted). Seeing this channel does not grant its memory's record, so use memoryId for the address.
loc String! The reserved address of the chat root (e.g. chats:team).
name String!
kind ChannelKind!
description String
chatRootNodeId ID! The chat root node this Channel IS the entity for (one-to-one).
chatRootUrn String #1171 — the Channel's ADDRESS: its chat root's node URN (hrn:node:<org>:<memory>:<loc>). A channelRef takes TWO FORMS — an id, or a chat-root node ref — and the node ref is accepted in every spelling the node resolver takes (`urn:node:`, bare fully-qualified, canonical `::`); this field emits the one to copy. COPY it rather than composing one: a Channel a ref fails to name is indistinguishable from one you may not read. NULL when the server has no flat-v2 address it can safely advertise — commonly a pre-v2 compound host memory URN, which flattens into a node URN that cannot be split back. It does NOT mean the Channel is unaddressable in principle (a canonical `::` spelling can still resolve one); it means the server will not hand you a string it would itself reject. Use `id` there; it always works.
lastSeq Int! Highest seq the allocator has issued — a watermark, not a count.
incarnation Int! #2181 — which incarnation of the Channel this is. An opaque, stable integer that rises when a supported recreation reuses the Channel under the same id; seqs and read cursors can survive it, so a pinned read or mark names this value. Compare for equality only.
lastMessageAt DateTime
createdAt DateTime!
updatedAt DateTime

ChannelReadState

Spec 049 Phase 7 — where an attendee is up to on a Channel (D-2026-09-13-009). Outside the register; keyed on the ATTENDEE (a Worker, or an Agent in an App); advances are monotonic. Mute is session state, never here.

Field Argument Type Description
attendeeUrn String
channelId ID!
lastSeenSeq Int!
updatedAt DateTime!
channelIncarnation Int! #2181 — the Channel's CURRENT incarnation (the same value as Channel.incarnation).
cursorIncarnation Int #2181 — the incarnation the stored cursor was last RAISED under. NULL is a legacy cursor: it is never backfilled and never relabelled. Treat your cursor as current only when this equals both channelIncarnation and the incarnation you read, and lastSeenSeq >= your seq.

ChannelsPage

Field Argument Type Description
items [Channel!]!
total Int!

Chat

A saved chat in one of the chat-scope tiers.

Per spec 017, scope is set at chat creation and immutable thereafter. private chats live in the author's personal-class memory; shared chats live in the App's app-class memory and are readable by every AppMember of that App.

Field Argument Type Description
id ID!
aiConfigChoice String #3957 (hrn:node:hadronmemory.com:specs:cor:dmo:050:10): the AI config choice stored with this chat — `default` or one of the App's config ids — or null when the chat stored none (it then follows the App's chatbot config, else `default`).
loc String!
title String!
conversationName String
stageName String
completedConversations [String!]! Names of conversations this chat has completed, in first-completion order; an empty list for encrypted rows means the state is unreadable, not proof that none completed. hrn:node:hadronmemory.com:specs:cor:cht:030:02
messageCount Int!
createdAt DateTime!
lastMessageAt DateTime
scope ChatScope! 017-chat-visibility-and-personal-memory.
createdBy ID The chat's author (chat-root node's createdBy). Null for legacy chats predating createdBy persistence. Surfaces who started a shared chat so the portal can distinguish own vs other-member shared chats in the list.
servedPrompts ServedPromptsPage! #2047 / hrn:node:hadronmemory.com:specs:cor:agt:040:03: the boot prompt this chat was served, once at its start and again whenever its served revision changed. Readable only by whoever manages the App the chat runs in, never by its end user; everyone else gets an empty page.
limit Int
offset Int

ChatAiConfigChoice

3957 (hrn:node:hadronmemory.com:specs:cor:dmo:050:10): one entry of the list a chat chooses its AI config from. No key material.

Field Argument Type Description
value String! `default` for the walk entry, else the config id: the value to send back as aiConfigChoice.
name String!
provider String Null for the `default` entry, which names no single config.
model String
isDefault Boolean!
isAppChatbotConfig Boolean! True for the App's own chatbot config (App.chatbotAiConfigId).
toolChoice ChatToolChoice #4005: the server's tool-choice decision for this config's provider and model, judged verbatim. Null for the `default` entry, which names no single config.

ChatMessage

One chat message in history, as returned by chatHistory.

Field Argument Type Description
role String!
content String!
seq Int
createdAt DateTime!

ChatPage

2212 A3 — one page of the caller's chats with an Agent, counted over the same chats.

Field Argument Type Description
items [Chat!]!
total Int!
hasMore Boolean!

ChatProbeOutcome

4005: the outcome of the chat probe.

Field Argument Type Description
status ChatProbeStatus!

ChatPromptResult

Field Argument Type Description
systemMessage String!
tools JSON
messageHistory JSON!
summarizationNeeded SummarizationRequest #1115 — ALWAYS NULL since 2026-09-04. It used to fire every 20 messages and ask the caller to produce a summary, but the summary it asked for is replayed to the model as an ordinary user turn beside the messages it summarises, so the loop made the transcript longer. Disarmed rather than removed: the field is nullable, was absent 19 turns in 20, and every caller already handles that. Re-arming needs the design in #1115.

ChatResponseResult

Field Argument Type Description
displayMessage String!
stageTransitioned Boolean!
newStageName String
rejectedNextStage String The stage name the turn asked for that is not one of the conversation's stages (hrn:node:hadronmemory.com:specs:cor:cht:030:02). The chat did not move; the turn is recorded. Null when the name was accepted or none was given.
conversationHandoff String
chatEnded Boolean!
conversationCompleted String Conversation completed by this turn's explicit goal_reached flag, or null. hrn:node:hadronmemory.com:specs:cor:cht:030:02
detourReturned Boolean! Whether this turn returned the chat from a detour to the conversation and stage the most recent active detour left. False when a completion rule fired instead, or routing was skipped. hrn:node:hadronmemory.com:specs:cor:cht:030:02
routingSkipped Boolean! Routing edits were skipped because a concurrent turn moved the chat from the decision's origin. hrn:node:hadronmemory.com:specs:cor:cht:030:02
onTrack Boolean!
offTrackReason String

ChatStartResult

Field Argument Type Description
chatId String!
systemMessage String!
tools JSON
conversationName String
stageName String

ClaimUntrackedTaskItemsResult

3125 S3: what claimUntrackedTaskItems created, in claim order.

Field Argument Type Description
tasks [AgentTask!]!
complete Boolean!
incompleteReason String
refusalCode String The stable code of the refusal that stopped the walk; null unless incompleteReason is claim_refused.

Comment

1606 — feedback about a node (hrn:node:hadronmemory.com:specs:cor:dmo:110). A comment is a node of type

comment in its target's memory, readable by exactly who can read that memory. It is never part of its target's content, never approved or minted, and never authoritative.

Field Argument Type Description
id ID!
urn String!
portalUrl String The portal page of the comment node; null when FRONTEND_URL is unset.
target CommentTargetRef!
threadRootId ID Null for a top-level comment; else the thread's top-level comment.
isTopLevel Boolean!
anchorRevision Int! The target revision the thread was written against (replies inherit their thread's).
anchorApprovalHash String The target fingerprint at anchorRevision: 64 lowercase hex, or null for encrypted targets (hrn:node:hadronmemory.com:specs:cor:dmo:110:01).
anchorIsCurrent Boolean! anchorRevision equals the target's current revision. When false, show the comment as about an older revision (hrn:node:hadronmemory.com:specs:cor:dmo:110:01).
quote String Null when deleted.
body String Null when deleted: the stub shows the state, not the text.
state CommentThreadState Top-level only; null for a reply.
deleted Boolean! #1721 — deleted with deleteComment. A deleted comment is shown only as a stub with no text, kept while it has live replies (hrn:node:hadronmemory.com:specs:cor:dmo:110:05).
deletedAt DateTime
deletedBy CommentActorRef Who deleted it: its author, or a memory manager.
resolvedAt DateTime
resolvedBy CommentActorRef
author CommentAuthor!
viewerIsAuthor Boolean! Whether the caller is this comment's author (the edit and delete right). Computed with the same author key the server enforces.
provenanceUser CommentActorRef Worker comments only: the user who bound the worker session, shown as provenance, never as author. Null for other comments, and for callers who cannot write the memory.
createdAt DateTime!
updatedAt DateTime When the comment row last changed: an edit, or a delete that leaves a stub. Resolve and reopen never change it. To show a comment as edited, use editedAt.
editedAt DateTime When the body or quote was last edited; null when it never was. Only an edit sets it (hrn:node:hadronmemory.com:specs:cor:dmo:110:12).
editedBy CommentActorRef Who last edited the body or quote; null when it never was.
revSeq Int! The comment's write counter. Pass it as expectedRevision to edit, delete, resolve or reopen. A comment keeps no revision history, so there are no earlier revisions to read.

CommentActorRef

1606 — a public projection of a comment's author, resolver or provenance user. Never the full User/Worker/Agent/App object (#552).

Field Argument Type Description
id ID!
name String
handle String Users only.
urn String Workers, agents and Apps: the canonical URN, when it can be composed.

CommentAuthor

1606 — a comment's author. Exactly the refs its kind names are set.

Field Argument Type Description
kind CommentAuthorKind!
worker CommentActorRef WORKER.
user CommentActorRef USER and USER_AGENT.
agent CommentActorRef USER_AGENT only.
app CommentActorRef APP.

CommentSummary

1606 — the trust cue (hrn:node:hadronmemory.com:specs:cor:dmo:110:07). Counts live threads; zeros on a memory that cannot hold comments.

Field Argument Type Description
oldestOpenThreadAt DateTime Earliest creation time of a live open root comment, or null. Replies, edits and reopen times do not move it. Null on synthetic inherited/install summaries. Proposed addition built on the #3494 gate (hrn:node:hadronmemory.com:specs:cor:api:090:02).
openThreads Int!
resolvedThreads Int!
comments Int! Every live comment, top-level and replies, deleted stubs included.
viewerOpenThreadId ID The caller's own open, live top-level thread on this node, if any: one per author (hrn:node:hadronmemory.com:specs:cor:dmo:110:05).

CommentTargetRef

1606 — the node a comment concerns. Same memory as the comment, so the same read gate.

Field Argument Type Description
id ID!
urn String!
name String!
nodeType String!
revSeq Int! The target's current revision (Node.revision).

CommentThread

Field Argument Type Description
root Comment!
replies [Comment!]! Oldest first; at most the first 200.
replyCount Int! Every live reply, including any beyond the returned 200.

CommentThreadPage

Field Argument Type Description
items [CommentThread!]! Newest thread first.
total Int!

CompiledBootPrompt

2046 — the result of a compile: the new unapproved revision of the compiled node.

Field Argument Type Description
node Node!
revNo Int! The revision this compile wrote.
contentHash String! SHA-256 hex of the compiled text.
pointerSet Boolean! Whether this compile wrote the pointer.
lintWarnings LintWarningPage Current warnings for the revision just compiled; null when unavailable.
first Int
after String
approvalIssued Boolean! Always false: a compile never approves or signs.

CompiledPromptOccurrence

One recorded source/include occurrence; contains no source text (hrn:node:hadronmemory.com:specs:cor:agt:040:12).

Field Argument Type Description
order Int!
depth Int!
parent Int
kind String!
nodeId ID!
revNo Int!
hash String!
replacesNodeId ID
position CompiledPromptTagPosition
selection CompiledPromptSelection!
pruned Boolean Null when the source or its retained snapshot is unreadable; otherwise whether revision text is absent.

CompiledPromptProvenancePage

A page of one compiled revision's immutable provenance (hrn:node:hadronmemory.com:specs:cor:agt:040:12).

Field Argument Type Description
nodeId ID!
revNo Int!
contentHash String!
version Int!
pruned Boolean!
items [CompiledPromptOccurrence!]!
total Int!
hasMore Boolean!

CompiledPromptSelection

Effective include selection settings recorded by the compiler (hrn:node:hadronmemory.com:specs:cor:agt:040:12).

Field Argument Type Description
rev Int
approved Boolean!
signed Boolean!

CompiledPromptTagPosition

One-based position of an include tag (hrn:node:hadronmemory.com:specs:cor:agt:040:12).

Field Argument Type Description
line Int!
column Int!

ConnectionFlow

Where one connect flow is (#2913, hrn:node:hadronmemory.com:specs:cor:dmo:080:04). Scalars only: it never hands out the connection's own fields.

Field Argument Type Description
status ConnectionFlowStatus!
connectionId ID The connection the flow created, or on a reconnect the existing one for the same organization, provider and account. Null unless CONNECTED.
failureCode String The stable code the done page shows (for example access_denied). Null unless FAILED.

ConnectionGrant

A user-owned connection's scoped delegation to an App install (spec-042 Track B, #593). The connection OWNER grants a specific App scoped access to their mailbox/calendar; the enforcement gate is requireEmailConnection. The grantee App is exposed as SCALARS only (never a nested App object), so a cross-org grant can't reach the App keys/members. Token material is never exposed.

Field Argument Type Description
id ID!
connectionId ID!
granteeAppId ID! The App install this grant delegates to.
granteeAppUrn String Canonical URN of the grantee App (hrn:app:<root>:<slug>), or null if unresolvable.
granteeAppName String
scopes [String!]! Covered scopes: mail.read, mail.send, calendar.freebusy, calendar.read, drive.read.
expiresAt DateTime ISO-8601 expiry, or null for perpetual (until revoked).
createdAt DateTime!

ConnectionGrantsPage

Field Argument Type Description
items [ConnectionGrant!]!
total Int!

ConnectionStart

The start of a connection's OAuth flow (#2897). Open authorizeUrl in a browser; the consent step belongs to the provider and the browser ends on a page this server hosts, so the portal is not involved. Find the connection this flow made with connectionFlow(flowId) (#2913, hrn:node:hadronmemory.com:specs:cor:dmo:080:04).

Field Argument Type Description
flowId ID! The id of this flow. connectionFlow(flowId:) says where it is: pending, the connection it made, or the failure code it ended with. Only the user who started the flow may read it, for one hour from the start.
provider ConnectionProvider!
orgId ID! The org the connection will be attached to.
authorizeUrl String! The server URL to open in a browser. Its nonce is single-use and short-lived (expiresAt); a second visit is refused. Treat the URL like a password until it has been opened once.
expiresAt DateTime! When authorizeUrl stops working. Start again after this.

ContextReset

2162 — a worker's context reset (hrn:node:hadronmemory.com:specs:cor:agt:050:27): a shed, never a session end. One per

task at most. phase is requested, claimed, checkpointed, stop-granted, agent-stopped, relaunched, done, refused or failed; reason names why a reset was refused or failed, from a closed set. epoch moves at the claim and at every cancellation: a host step naming another is STALE_EPOCH.

Field Argument Type Description
id ID!
appId ID!
workerId ID!
sessionId ID!
taskId ID Null for a reset with no task: one asked for by the Agent's context cap (#4225).
cause String! #4225: what asked for the reset: task-end (a task's finish or cancel) or context-cap (the Agent's context cap, S4b).
hostId String
hostOperationId ID
phase String!
reason String
epoch Int!
requestedAt DateTime!
claimedAt DateTime
recoveryRegisteredAt DateTime
checkpointNode String #3300 (hrn:node:hadronmemory.com:specs:cor:agt:050:27 part 3; hrn:node:hadronmemory.com:specs:cor:agt:070:04): canonical v2 checkpoint URN fixed at registration and kept after the reset ends or the node moves or is deleted. Null before registration. Legacy id-only rows derive it while the node row exists, otherwise null. Reset state behind the existing host-key gates, not a node read.
stopGrantedAt DateTime When the single stop was granted; the host may act on it only within stopLeaseMs of its own send time.
stopLeaseMs Int
agentStoppedAt DateTime
relaunchedAt DateTime
releasePendingAt DateTime When a cancellation found a stop lease outstanding: the resetting mark lifts no earlier than this.
endedAt DateTime

ContextResetStep

2162 — what a context reset step answered.

Field Argument Type Description
reset ContextReset!
refused String This step refused or failed the reset, and why; the reset has ended. Null when the step was accepted.
replayed Boolean! The step had already been made: the recorded answer is returned, nothing changed.

CreateMemorySharePayload

Field Argument Type Description
memoryShare MemoryShare!

CreditBalance

Field Argument Type Description
organizationId ID!
balanceMicroCents String!

CreditLedgerEntry

046-usage-metering: append-only org credit ledger row. Signed micro-cents as a base-10 integer string (grants +, debits -).

Field Argument Type Description
id ID!
organizationId ID!
kind String!
amountMicroCents String!
expiresAt DateTime
sourceType String
sourceId String
note String
createdAt DateTime!
createdBy String

CreditLedgerEntryList

Field Argument Type Description
items [CreditLedgerEntry!]!
total Int!

DashboardWidget

One widget the caller has placed on their /app/dashboard grid (#772).

Field Argument Type Description
id ID!
type DashboardWidgetType!
span Int! Columns spanned on the 12-col desktop grid.
rowSpan Int! Rows spanned on the fixed-height row grid (#788).
position Int! 0-based sort order among the caller's widgets.
config JSON Widget-instance settings; shape is widget-defined (#788).

DashboardWidgetData

Data for ONE placed widget — the portal fans this out by widgetId (#797).

Field Argument Type Description
widgetId ID! The placement this payload belongs to — fan out by this, not by type (#797).
type DashboardWidgetType!
data JSON! The widget-specific payload (e.g. memory-stats => { memoryCount }).

DashboardWidgetPreset

806 — a named, saved widget configuration. A palette entry: applying one

COPIES its config into a placement, so later edits to the preset do not reach placements already seeded from it, and deleting it never orphans a placement. Owner-only — no org, no sharing.

Field Argument Type Description
id ID!
type DashboardWidgetType! The widget type this configuration belongs to. Immutable after creation.
name String! Display name, unique among the caller's presets for this type.
config JSON! The saved settings, shape widget-defined — becomes a placement's config verbatim.

DashboardWidgetPresetPage

2213 — one page of the caller's saved widget presets.

Field Argument Type Description
items [DashboardWidgetPreset!]!
total Int!
hasMore Boolean!

Decision

1641 — a human decision: a governed node (role decision) under a decision log, written only by the

decision operations. Its content is rendered from this structured payload, so an approval covers exactly what was asked and answered. Plan: hrn:node:hadronmemory.com:hadron-server:design:decision-nodes.

Field Argument Type Description
id ID!
urn String!
portalUrl String The decision's own page, where its card renders. Copy it; never build it.
code String! Permanent: DA, DB, … issued in sequence by its log, never reused.
n Int!
logId ID
title String!
urgency DecisionUrgency!
tier DecisionTier!
authorizes Boolean!
archival Boolean! Migrated history that is never usable as an authorization.
state DecisionState! DERIVED on every read. Rely on a ruling only while it is DECIDED.
context String
parts [DecisionPart!]!
blocks [DecisionRef!]! What is waiting on this decision.
sources [DecisionRef!]!
followUps [DecisionRef!]! Spec citations the ruling must reach.
deciderIds [ID!]!
deciders [CommentActorRef!]!
viewerIsDecider Boolean! True when the caller is a decider, including through an account merged into theirs (#1715).
identityMerges [DecisionIdentityMerge!]! Account merges the stored user ids follow: the record keeps the merged-away id (#1715).
askedBy DecisionActor!
askedAt DateTime
answeredAt DateTime When the last part was answered; null while any part is open.
withdrawn DecisionWithdrawal
evidence DecisionEvidence!
revSeq Int! The node's current revision: the expectedRevision of the next change.
node Node

DecisionActor

1641 — an authenticated actor: taken from the principal, never supplied by a client. Public projections only (#552).

Field Argument Type Description
userId ID
workerId ID
appId ID
user CommentActorRef
worker CommentActorRef
app CommentActorRef

DecisionAnswer

Field Argument Type Description
key String The chosen option; null for a free-text answer.
text String
freeform Boolean!
byUserId ID! The decider whose credential recorded it.
at DateTime!
via DecisionAnswerVia!
source DecisionRef Where the answer was given (a claim).
reason String
claimedBy String An imported answer's recorded speaker (a claim, never rendered as the authenticated answerer).
recordedByUserId ID

DecisionApprovalEvidence

Field Argument Type Description
byUserId ID
by CommentActorRef
revision Int! The revision approved.
approvedAt DateTime!
integrity String! INTACT, TAMPERED, SUPERSEDED or NOT_APPROVED: the approval hash checked against the live text.
byDecider Boolean! Whether the approver is one of the decision's deciders (only then does it count).

DecisionEvidence

Field Argument Type Description
approval DecisionApprovalEvidence The latest approval on record, whoever gave it.

DecisionIdentityMerge

1715 — an account merge that a user id stored in a decision or a log follows.

Stored ids are never rewritten by mergeUsers, because they are part of the authenticated record: the record still names fromUserId, and that account now acts as toUserId. A chain of merges is listed link by link, oldest first.

Field Argument Type Description
fromUserId ID!
from CommentActorRef
toUserId ID!
to CommentActorRef
mergedAt DateTime!

DecisionLog

1641 — a decision log's settings (never a decision, never approved).

Field Argument Type Description
id ID!
urn String!
portalUrl String
loc String!
name String!
prefix String! Codes are this prefix plus letters: D → DA, DB, …
lastCode Int! How many codes have been issued (withdrawn and purged ones included).
defaultDeciderIds [ID!]!
eligibleDeciderIds [ID!]!
defaultDeciders [CommentActorRef!]! Who decides a decision asked without naming deciders.
eligibleDeciders [CommentActorRef!]! Who else a decision may name as a decider. A decision's deciders are narrowed from these, never widened.
purges [DecisionPurge!]!
identityMerges [DecisionIdentityMerge!]! Account merges the stored user ids follow: the record keeps the merged-away id (#1715).
revSeq Int!

DecisionOption

Field Argument Type Description
key String! The option id an answer names.
label String!
meaning String
cost String

DecisionPage

Field Argument Type Description
items [Decision!]!
total Int! Matching decisions before paging.

DecisionPart

Field Argument Type Description
n Int! Permanent within the decision; amendments add parts, never renumber.
citation String! The citation of this part, e.g. DU-1.
question String!
options [DecisionOption!]!
recommendation DecisionRecommendation Null when the asker deliberately gave none (see noRecommendationReason). Never pre-selected.
noRecommendationReason String
answer DecisionAnswer
answerHistory [DecisionAnswer!]! Earlier answers to this part, oldest first: a re-answer appends, never replaces quietly.

DecisionPurge

Field Argument Type Description
code String!
byUserId ID!
by CommentActorRef
at DateTime!
reason String!
contentHash String! sha256 of the purged decision's rendered content.

DecisionRecommendation

Field Argument Type Description
key String!
by DecisionActor! Who recorded the recommendation (authenticated).
reason String
attributedTo String A relayed recommendation's original author, as a claim.

DecisionRef

1641 — a reference: exactly one of an external ref (hadron-server#1640, team:6783), a node id or URN, or a spec citation.

Field Argument Type Description
ref String
node String
spec String

DecisionVerification

1641 — verifyDecision: the one evaluation's findings.

Field Argument Type Description
state DecisionState!
findings [String!]! NO_BLOCK, BLOCK_INVALID, UNKNOWN_CODEC, UNKNOWN_RENDERER, RENDER_MISMATCH, DATA_MISMATCH, APPROVAL_HASH_MISMATCH.
codec String
renderer String
revision Int!
approvedRevision Int
approvalIntegrity String!
approvalByDecider Boolean!

DecisionWithdrawal

Field Argument Type Description
by DecisionActor!
at DateTime!
reason String!

4280 — a defect linked to the pull request it escaped from (the review.defect-linked event on the PR's build task).

Field Argument Type Description
taskId ID! The PR's build task.
defect String! The defect's issue URL, as given.
introducedAtHead String The head that introduced the defect, or null when the link names none.
eventId ID! The review.defect-linked event that records the link.
linkedAt DateTime!
created Boolean! False when the pair was already linked: this is the existing link, and nothing was written.

DeleteMemorySharePayload

Return shape for deleteMemoryShare. Both fields are RESOLVED primary keys, so a caller who passed a URN / email / handle can correlate the deletion. granteeId is the caller themselves on the self-removal path.

Field Argument Type Description
memoryId ID!
granteeId ID!

DeleteTeamRolePayload

Result of deleteTeamRole (#1002).

Field Argument Type Description
role String! The role slug that was retired.
nodesDeleted Int! Nodes tombstoned — the roles:<role> definition plus any sub-nodes under it (a roles:<role>:notes is content OF the role and retires with it). Soft, so the subtree is recoverable.

DeleteWorkerPreview

3599: a non-reserving delete preview. No census detail is returned.

Field Argument Type Description
workerId ID!
attestationRequired Boolean! Always true: the real delete still requires the caller's explicit external-attribution confirmation.

DeliveryBatch

One ready-to-type delivery for one worker. The id is a signed proof bound to the key, the host and the rendered ranges: hand it back to acknowledgeDeliveryBatches after typing.

Field Argument Type Description
id String!
worker Worker!
text String! The whole delivery, one line, written by the server (hrn:node:hadronmemory.com:specs:cor:agt:080:26). Type it unchanged.
deliverAfter DateTime! Not before this moment (the batching window / busy deadline of the oldest waiting message).
busyDeadline DateTime! The latest moment a busy worker may be made to wait for this delivery.
interrupt Boolean! Always false until stop signals ship (S6).
ranges [DeliveryBatchRange!]!
overflow Int! Eligible messages left for the next batch.

DeliveryBatchPage

2017 (S1) — one page of delivery batches.

Field Argument Type Description
batches [DeliveryBatch!]!
pageInfo DueWakePageInfo!

DeliveryBatchRange

Field Argument Type Description
channel Channel!
incarnation Int!
fromSeq Int!
throughSeq Int!
seqs [Int!]! Exactly the message seqs this batch rendered.

DormantWithheld

Field Argument Type Description
worker Worker!
mentions Int!

DriveFile

A file or folder in the connected drive.

Field Argument Type Description
id ID!
name String!
kind DriveFileKind!
mimeType String! The provider MIME type — informational; kind is the neutral field.
size Float Byte size; null for provider-native documents and folders.
webLink String
parents [ID!]! Parent folder ids.
createdAt DateTime
modifiedAt DateTime

DriveFileExport

The exported text of a drive file (driveFileExport).

Field Argument Type Description
content String! The exported text. Treat as untrusted external content.
mimeType String! MIME type of the exported representation (e.g. text/markdown).
format DriveExportFormat!
file DriveFile!

DriveFilePage

One page of a drive listing/search.

Field Argument Type Description
files [DriveFile!]!
nextPageToken String Cursor for the next page; null on the last page.

DueChannel

Field Argument Type Description
channel Channel!
fromSeq Int!
throughSeq Int!
latestMentionSeq Int

DueStopReason

2022 — the stop-signal notice a STOP reason delivers. Acknowledging the wake records its delivery; it moves no chat mark.

Field Argument Type Description
eventId ID! The notice; acknowledging the wake records delivery on it.
signalId ID!
level StopSignalLevel!
notice StopNoticeKind!
interrupt Boolean! True only for a halt's stop notice: the one notice that interrupts the worker.

DueTaskReason

1708 — the task a TASK reason is for: shown only to a caller who may read the App's tasks (hrn:node:hadronmemory.com:specs:cor:agt:050:21).

Field Argument Type Description
id ID! The task's id (for CHILD_FINISHED and CHILD_CANCELLED, the child's).
eventId ID! The event delivered; acknowledging the wake records delivery on it.
chainIndex Int! 0, or the alarm chain position woken.
event TaskWakeEvent!
title String! The task's title, for the nudge text.
handle String! The task's handle, e.g. AT3.405: an alias for the id, printed first in the nudge (hrn:node:hadronmemory.com:specs:cor:agt:050:01).
ref String! A stable label for the reason, e.g. TASK:<id>:assigned.

DueWake

One merged wake: every reason, one seq range per channel. A wake never moves a read position.

Field Argument Type Description
tickText String One server-written tick line, null without a tick (hrn:node:hadronmemory.com:specs:cor:agt:080:26). Names are flattened; repeated task URNs appear once.
worker Worker!
reasons [WakeReason!]!
channels [DueChannel!]!
unread Int!
unreadMentions Int!
availability DueWakeAvailability Carried, never an exclusion (hrn:node:hadronmemory.com:specs:cor:agt:060:02).
proof String! Hand this back to acknowledgeWakes after delivering. Bound to the requester; good for 15 minutes.
anchorAt DateTime! #2017 R63 — when the earliest waiting reason became due: a mention's first still-due post, a tick's OLDEST unacknowledged tick time, a task event's time. Never restarted by a re-offer or a join (hrn:node:hadronmemory.com:specs:cor:agt:080:27).
deliverAfter DateTime! Not before this moment: the anchor plus the App's batching window (the shared cadence floor).
busyDeadline DateTime! The latest a busy worker may be made to wait: the anchor plus the App's busy delay.

DueWakeAvailability

Field Argument Type Description
state String!
reason String
until DateTime
setAt DateTime!

DueWakePage

1748 — one page of due wakes. Counts and ranges only (hrn:node:hadronmemory.com:specs:cor:agt:080:23).

Field Argument Type Description
status DueWakeStatus!
withheld Int! Wakes held back by the daily budget; each stays due.
wakes [DueWake!]!
dormant [DormantWithheld!]! Dormant workers with relevant mentions, and how many: withheld, never dropped silently.
pageInfo DueWakePageInfo!

DueWakePageInfo

Field Argument Type Description
hasNextPage Boolean!
endCursor String

Edge

Field Argument Type Description
id ID!
source Node The live source node, or null when deleted or when its memory is unreadable. Cross-memory edges never grant access to an otherwise unreadable endpoint. Deleted-node inspection uses the explicit recovery graph.
target Node The live target node, or null when deleted or when its memory is unreadable. Deleted-node inspection uses the explicit recovery graph.
urn String! Fully-qualified edge URN (hrn:edge:<root>:<memory>:<loc>), composed server-side from the edge's (source-side) memory URN + loc (#481 parity — edges are loc-addressed peers of nodes, spec 037).
loc String! Colon-delimited path within the (source node's) memory — the edge's identity and the suffix of its URN hrn:edge:<root>:<memory>:<loc>.
name String Free-form relationship name (e.g. imports, depends_on). Optional since spec 037 — loc is the identity. (Was the required 'label'.)
description String Longer gloss carried for API consumers. NOT rendered on agent node reads, whose Related:/Referenced by: lines show the edge name (#721: name is the display label). Put the label you want seen in name (#1057).
isRunnable Boolean If true, this edge can be executed/run (task automation, conversation transitions). Mirrors Node.isRunnable.
condition JSON JSONLogic gating expression. Null = always fires. Validated against the v1 operator subset and the FOUR variable scopes — memory.*, chat.*, agent.*, message.data.* (VALID_SCOPE_PREFIXES; anything else is UNKNOWN_SCOPE). The time builtins now() and today() are a SEPARATE constant, not a fifth scope: they are whole references rather than prefixes, and the evaluator pre-resolves them from the request clock. Until #1246 this said "five variable scopes" and listed the builtins as one of them — a count and a category error in one sentence. See hadron-docs/docs/reference/edge-conditions.md.
priority Int! Resolution-order hook (lower = earlier; default 0). When two edges share a priority, fall back to insertion order.
data JSON
governedKind EdgeGovernedKind The edge's OWN stored governed kind (#2124): null for an ordinary edge, otherwise INCLUDE, COMMENT_ANCHOR or COMMENT_REPLY. Read-only; it rides the same gate as the edge, is never inferred from name or loc, and no edge write accepts it. A stored value this server does not support is an UNSUPPORTED_EDGE_GOVERNED_KIND error, never null.
createdAt DateTime! #1151 - when the edge was created.
updatedAt DateTime #1151 - when the edge row last changed (stamped on create too; null only for a row inserted outside the API).
createdByUser NodeRevisionEditor #1151 - the User behind this edge's creation, as handle and URN only (the revision-editor projection; never a raw id). Null when the stored creator resolves to no live user (a system job, an app key, a deleted user; the stored value is never echoed), for edges written before attribution was stamped (not backfilled), and for a caller who cannot read the memory the edge lives in (an edge's memory is its source side), so a cross-memory edge never names another tenant's user.
updatedByUser NodeRevisionEditor #1151 - the User behind the last update of this edge; null under the same conditions as createdByUser.

EdgesPage

Field Argument Type Description
items [Edge!]!
total Int!

EditorLockResult

Field Argument Type Description
locked Boolean!
lockedBy String
expiresAt DateTime

EffectiveAccess

issue #323: the effective access a single user has to a single resource, with the grants that confer it. An empty grants list (with all capabilities false and role null) is a first-class 'no access' answer, NOT an error.

Field Argument Type Description
user User!
resourceUrn String! Canonical (grammar-v2, hrn:-prefixed) URN of the resolved resource, emitted the same way the entity's own urn field emits it — so it can be fed straight back into another query or command. Two exceptions have no URN by nature: an AiServiceConfig yields its id, and a user yields hrn:user:<handle>.
resourceKind String! memory | node | app | agent | aiServiceConfig | organization | user.
canRead Boolean!
canWrite Boolean!
canManage Boolean! Manage grants / settings (admin/owner-equivalent).
canDelete Boolean!
role String Highest single clean role label (e.g. owner, writer, ADMIN); null when access is purely capability-based or absent.
grants [AccessGrant!]! The reasons access is granted. Empty means no access. Ordered strongest-first.

EffectiveActionPolicy

The standing-chain policy debug surface (#510): per-layer verdicts for one action (cor:acl:040:02). Trigger/run links are per-trigger and not part of the standing chain.

Field Argument Type Description
allowed Boolean!
layers [PolicyLayerVerdict!]!

EffectiveModelGroup

2831 - a model group as it applies in one App (hrn:node:hadronmemory.com:specs:cor:agt:060:12).

Field Argument Type Description
name String!
patterns [String!]!
origin ModelGroupOrigin!

EmailDraftInfo

Result of emailSaveDraft: the provider-side draft (it lives in the mailbox's Drafts folder, not in any platform table — spec 002 US5).

Field Argument Type Description
draftId ID!
conversationId ID

ExchangeConnection

A connected PROVIDER ACCOUNT (identity record) — despite the name, this one type carries mailboxes, calendars and Drive accounts alike; the provider field below says which, and each routes to its own capability tool. Provider state lives in that tool, never here.

Operations are identity-scoped: the connection's OWNER may perform them, and an App/headless caller may perform those covered by a live ConnectionGrant whose scopes include the operation's (requireEmailConnection enforces both branches, fail-closed for an unmapped operation). list and delete stay org-ADMIN management operations.

Field Argument Type Description
id ID!
organizationId String!
userId String!
mailboxEmail String!
displayName String
provider String! Provider backing this connection. Dispatched per-connection through the tool registry: `ms-exchange`, `gmail`, `google-cal`, `google-drive`. (This said "'ms-exchange' today" until #1232 — true when written, and three providers out of date by the time it was published.)
syncEnabled Boolean!
syncStatus SyncStatus!
lastSyncAt DateTime
lastError String
createdAt DateTime!
updatedAt DateTime!

ExchangeConnectionPage

2213 — one page of an org's exchange connections.

Field Argument Type Description
items [ExchangeConnection!]!
total Int!
hasMore Boolean!

ExchangeFolder

Field Argument Type Description
id ID!
displayName String!
totalItemCount Int
unreadItemCount Int

ExchangeMessage

Field Argument Type Description
id ID!
subject String
from String
receivedDateTime DateTime
isRead Boolean
bodyPreview String
body String
hasAttachments Boolean

FindNodesResult

Envelope for findNodes (cor:api:090) — the unified node list + search field (it replaced the removed nodes + nodeSearch queries). hits carry per-hit score + vector metadata; passages carry chunk-granularity results; reason/degraded surface no-index / reduced-fidelity outcomes.

Field Argument Type Description
hits [NodeHit!]!
passages [Passage!]!
total Int
reason String
degraded String Reduced-fidelity flag(s); hits are usable. May carry MULTIPLE comma-separated codes (e.g. 'no_vector_index,literal_fallback') — parse the set, never compare the whole string. Codes: no_vector_index, embedding_unavailable, literal_fallback, and_relaxed_to_or (a bare multi-term keyword query matched nothing under AND, so it was retried as OR and these hits match ANY term), scope_narrowed (spec 049: the scope this search ran under lists memories you cannot read; they were dropped and `scope.droppedCount` says how many).
scope SearchScopeInfo Spec 049 (D-2026-09-13-002): what this search was produced under. Null when no scope applied (the pre-049 accessible set, optionally org-narrowed).

GlobalSearchHit

One unified, flat globalSearch result — common fields across every entity type so a single ranked list renders uniformly. urn is null for an aiServiceConfig (no URN) and for a user with no handle or a not-URN-legal handle (a user's URN is hrn:user:<handle>); memoryId / organizationId are convenience handles for building canonical navigation paths.

Field Argument Type Description
entityType SearchEntityType!
id ID!
urn String
name String
description String
matchedField SearchField!
score Float!
memoryId ID
organizationId ID
handle String The entity's short handle when its kind has one (an agentTask's bare AT0.6508), else null. Render as given; never compose or parse.

GlobalSearchResult

Field Argument Type Description
scope SearchScopeInfo Spec 049: the scope the Memory + Node slices ran under (see FindNodesResult.scope). Null when no scope applied.
hits [GlobalSearchHit!]!
total Int! Total ranked matches for building a pager. BOUNDED CONTRACT: this is the count within the per-entity candidate cap (each entity type contributes at most a fixed number of candidates before scoring), not an unbounded COUNT. On very large result sets it under-counts; page slicing (offset/limit) operates over this bounded, fully-ranked list.
degraded [String!]! Notes when the search ran at reduced fidelity (e.g. content search skipped on encrypted memories).

Grant

A grant (#3789, hrn:node:hadronmemory.com:specs:cor:acl:140:05): ids and scalars only, so no other entity's field resolvers are reachable through it. Its stored facts as stored, and allows and state, which are computed (#4173).

Field Argument Type Description
id ID!
appId ID!
action String! The registered action this grant allows.
values JSON The values it allows (a single value, a list or a wildcard); never a secret.
holderKind GrantHolderKind!
holderId ID!
issuerUserId ID The person who issued it: its signer (hrn:node:hadronmemory.com:specs:cor:acl:140:04). Null while it is pending. Null on an activated grant means the issuer's account was erased: it reads as issued by a deleted user, and stays as it was (hrn:node:hadronmemory.com:specs:cor:acl:140:08).
requestedByUserId ID
requestedByWorkerId ID
requestedBySessionId ID
startsAt DateTime
expiresAt DateTime
maxUses Int
useCount Int!
reason String!
createdAt DateTime!
activatedAt DateTime Null while the grant is pending (a pending grant allows nothing).
verificationKind String How the activation was verified, as stored; null while pending.
verifiedBy ID The person whose signature activated it; null while pending, and null once their account is erased (a deleted user, hrn:node:hadronmemory.com:specs:cor:acl:140:08).
signatureId ID
revokedAt DateTime
revokedByUserId ID #3711 (hrn:node:hadronmemory.com:specs:cor:acl:140:05, V56): who revoked or withdrew it, as a user id. Only the App's manager reads it (appGrants); every other read of the grant answers null. A worker requester's withdrawal records the person driving it. Null once that account is erased.
holderDepartedAt DateTime #3711 (V56): when the holder went (a person erased, a worker retired, an agent or App deleted); a fact, not a state. Only the App's manager reads it (appGrants); every other read answers null.
allows Boolean! Whether the grant allows its action right now, judged on the database clock by the one live function (activated, not revoked, holder not gone, App not deleted, started, not expired, not spent). A fact about this instant, never a lifecycle name.
state GrantState! #4173: the lifecycle state (hrn:node:hadronmemory.com:specs:cor:acl:140:03), the same on every surface that returns the grant.
signatureStatus GrantSignatureStatus! #3649 slice D (hrn:node:hadronmemory.com:specs:cor:acl:140:07) — its signatures, each re-verified on this read from the stored assertion. Readable by exactly those who may read the grant; it adds no reach.

GrantAction

3708 (hrn:node:hadronmemory.com:specs:cor:acl:140:02): one registered action a grant can allow. The registry is written only by a deploy; no call creates, changes or deletes an action. There is no plain-language summary here (its own slice).

Field Argument Type Description
name String! The dotted code, unique, e.g. schedule.create.
source String! Where the action comes from: PLATFORM today.
tool String The tool that performs it, if any.
parameters [GrantActionParameter!]! The parameters a grant of this action must supply.
enforcement String! The enforcement level the action DECLARES: what the platform promises, not an active guarantee. It says nothing about whether a gate enforces it today (schedule.create and webhook.create are not enforced until hadron-server#3483; the boot-prompt actions are checked where the grant is spent).
issuerRule String! A closed key naming who may issue a grant of this action.

GrantActionParameter

3708 (hrn:node:hadronmemory.com:specs:cor:acl:140:02, ruling 0255 item 2): one parameter an action declares.

Field Argument Type Description
name String! The parameter's name, as a grant's values name it.
type String! The kind of value it takes, e.g. node-ref.
refusesWildcard Boolean! True when a wildcard value is refused for this parameter.

GrantActionsPage

Field Argument Type Description
items [GrantAction!]!
total Int!

GrantSignature

3649 slice D — one signature on a grant. Only the passkey's label is ever shown.

Field Argument Type Description
id ID!
signer NodeRevisionEditor The person who signed, as handle and URN only. Null when their account was erased: a deleted user (hrn:node:hadronmemory.com:specs:cor:acl:140:08); the stored id is never echoed.
passkeyLabel String! The passkey's label; an erased person's reads 'Erased passkey'.
passkeyRevokedAt DateTime When the signer's passkey was revoked, if it was; the signature keeps its state.
version Int! The grant record version it was made on.
termsHash String! The terms hash it was made over (64 lowercase hex, hrn:node:hadronmemory.com:specs:cor:acl:140:09).
verifiedAt DateTime!
signingRequestId ID!
payloadVersion String!
state GrantSignatureState!

GrantSignatureStatus

3649 slice D — a grant's signatures. No grant state label is derived here.

Field Argument Type Description
state GrantSignatureState CURRENT if any signature is current, else the best of PENDING, EARLIER, CANCELLED; null with no signatures.
signatures [GrantSignature!]! Current signers first, then newest first.
integrityProblems Int! Records that fail re-verification or are inconsistent with the grant: reported, never listed as signatures.

GrantSigningRequest

3649 slice B (hrn:node:hadronmemory.com:specs:cor:acl:140:07, hrn:node:hadronmemory.com:specs:cor:acl:140:09) — a request for a person to sign ONE grant,

pinned at creation: the grant, its record version and its terms hash. No signer is named: whoever signs must be able to issue the grant (hrn:node:hadronmemory.com:specs:cor:acl:140:04), judged when they sign.

Field Argument Type Description
id ID! 128 bits of randomness.
grantId ID!
version Int! The grant record's version pinned at creation.
termsHash String! The terms hash pinned at creation (64 lowercase hex, hrn:node:hadronmemory.com:specs:cor:acl:140:09).
payloadVersion String! The payload version the signer signs: hadron-grant-signature-v1.
state GrantSigningRequestState! The effective state.
requestedBy SigningRequester!
createdAt DateTime!
expiresAt DateTime!
endedAt DateTime Null while OPEN. EXPIRED ends at expiresAt; every other end at the moment it happened (DB clock).
ceremonyUrl String! The server-hosted ceremony page where someone who may issue the grant signs it (hrn:node:hadronmemory.com:specs:cor:acl:140:07): the server origin plus /grant-signing/<id>, with no token. Copy it verbatim; never compose it. Signing there with a passkey activates the grant; no GraphQL or MCP call takes an assertion. An ended request's link only explains that it ended.

GrantsPage

Field Argument Type Description
items [Grant!]!
total Int!

GraphEdge

Slim edge projection for the graph view (issue #466) — endpoint IDs only.

Field Argument Type Description
id ID!
loc String!
name String
sourceId ID!
targetId ID!
governedKind EdgeGovernedKind The edge's governed kind (#2124); see Edge.governedKind.

GraphEdgesPage

Paged envelope for memoryEdges — total is the memory's full edge count.

Field Argument Type Description
edges [GraphEdge!]!
total Int!

GraphNode

Slim node projection for the graph view (issue #466) — only what a node-link graph draws.

Field Argument Type Description
id ID!
openThreads Int! #1606 — how many open discussion threads this node has: the node-list trust cue (hrn:node:hadronmemory.com:specs:cor:dmo:110:07). Batched per request.
loc String!
name String! Non-null — mirrors Node.name (the DB column is NOT NULL).
nodeType String! Non-null — mirrors Node.nodeType (NOT NULL, defaults to 'info').
tags [String!]!
seq Int Sibling sort order in the tree view (nullable; #513). Small scalar — kept in the slim projection.
isRunnable Boolean Whether the node can be run as a task — drives the tree action indicator (nullable; #513).
description String Short one-line description for graph tooltips / detail (nullable; #513). NOT the heavy body — content/abstract/data stay out of the slim projection.

GraphNodesPage

Paged envelope for memoryNodes — the standard limit/offset/total idiom; total is the memory's full node count.

Field Argument Type Description
nodes [GraphNode!]!
total Int!

HomeAssistantInstance

One registered Home Assistant instance (hadrontool-home-assistant registry, hadron-server#640). Org-owned. The long-lived access token is encrypted at rest and WRITE-ONLY: no field here ever returns it. The row grants nothing by itself; every run-time call walks the policy chain as 'tool.ha__<slug>__<op>' plus the run's action budget.

Field Argument Type Description
id ID!
organizationId String!
slug String! Run-tool name segment (ha__<slug>__<op>); lowercase [a-z0-9-], unique per org, immutable.
name String!
url String! Home Assistant base URL (e.g. https://ha.example.com or a Nabu Casa remote URL).
opAllowlist [String!]! Exposed-op allowlist over the closed op catalog; empty = every op. Lets an admin register a read-only instance.
enabled Boolean! Disabled instances fail run-tool resolution loud, same as an unregistered slug.
createdAt DateTime!
createdBy String
updatedAt DateTime!
updatedBy String

HomeAssistantInstancesPage

Uniform paginated list shape (cor:api:120).

Field Argument Type Description
items [HomeAssistantInstance!]!
total Int!

HomeAssistantOp

One op of the CLOSED Home Assistant op catalog, as admitted by a registry row's allowlist — what this query returns IS what a run can declare in data.tools. The catalog is static (no upstream round-trip).

Field Argument Type Description
op String! The op segment, e.g. call_service.
description String!
runToolName String! The run-tool / policy name: ha__<slug>__<op>.
inputSchema JSON The op's argument JSON Schema.

HostDesiredState

4224: the desired state of every worker one host runs, and the App's sweep mode.

Field Argument Type Description
hostId String!
sweepMode SweepMode!
workers [WorkerDesiredState!]!

HostKeyUse

1709 — one use of a host key (hrn:node:hadronmemory.com:specs:cor:agt:070:07).

Field Argument Type Description
id ID!
hostId String!
action String! register, collect, report, availability, read, (#1969) session: a refused session write (updateSession, endSession), or (#4292) an endAgentlessSession, accepted or refused, or (#1981) issue: a refused issueHostOperation; checkpoint: registerContextResetRecovery with checkpoint input (including replay/refusal).
operationId ID The operation a report was about.
count Int How many operations a collection returned, or workers a registration listed.
refusedCode String #1881 — the refusal code when the server refused this use (e.g. APP_KEY_SCOPE_REQUIRED); null for a use that succeeded. A refused use is recorded too (hrn:node:hadronmemory.com:specs:cor:agt:070:07: every use).
usedAt DateTime!

HostOperation

1709 — one typed operation issued to one host (hrn:node:hadronmemory.com:specs:cor:agt:070:02, :03). type is one of

worktree.create, worker.start, worker.deliver, worker.end, worktree.remove, worker.reset-context; args are its typed arguments (ids and name tokens only, never a command): worktree.create {workerId, repo, baseBranch, branchName, label}; worker.start {workerId, worktree, family, taskId?}; worker.deliver {workerId, sessionId, eventId}; worker.end {workerId, sessionId}; worktree.remove {workerId, worktree}; worker.reset-context {workerId, sessionId, taskId, resetId} (#2162). The per-type arguments are #1709's design, Proposed.

Field Argument Type Description
id ID!
appId ID!
hostId String!
type String!
args JSON!
workerId ID!
worker Worker
status HostOperationStatus!
issuedBy HostOperationIssuer!
issuedByUserId ID
issuedByWorkerId ID
issuedAt DateTime!
collectedAt DateTime
finishedAt DateTime
result JSON A success's typed result, by type: {worktree} for worktree.create, {sessionId} (the worker session the start's grant bound) for worker.start, {handoff} (a boolean: whether a handoff was written) for worker.end. Null for worker.deliver, worktree.remove and worker.reset-context, for a failure, and until the operation finishes.
failureReason String Why it failed, as the host said it.
issuedReason String #4231 — why the platform issued it when no task did: DESIRED_RUNNING for the start of a long-lived worker that should run and has no session (hrn:node:hadronmemory.com:specs:cor:agt:070:05, Proposed). Null for every other operation.
launchGrant String #1709 — worker.start only, and only in collectHostOperations' answer: the single-use launch grant to pass to the agent the host starts (it redeems it at startSession with its holder's own token). Short-lived; never stored in clear and never shown again. #1928: while it is live, a re-collection leaves the start out of the answer; once it expires, the next collection revokes it and delivers the start with a fresh one; once redeemed, the start is delivered with null here, so a restarted host can still report it. Null everywhere else.

HostOperationPage

Field Argument Type Description
items [HostOperation!]!
hasNextPage Boolean!
endCursor String Pass as after for the next page.

HostRegistration

1709 — a host's registration (hrn:node:hadronmemory.com:specs:cor:agt:070:01).

Field Argument Type Description
hostId String! The host's id within its App: the one its key's host:operate scope names.
label String!
pollIntervalSeconds Int!
registeredAt DateTime!
refreshedAt DateTime!
live Boolean! Refreshed within the App's lapse count of its poll intervals, now.
capabilities [String!]! #2162 — the capability-gated operation types this host declared it performs (hrn:node:hadronmemory.com:specs:cor:agt:070:01, Proposed): worker.reset-context. A host is never issued one it did not declare.
workers [HostRegistrationWorker!]!
refusedWorkers [HostRegistrationRefusal!]! #4222 — on registerHost's own answer only (empty on every read): the workers the host listed that were left out because the App's hostSetupSource is SERVER and the platform did not assign them to this host. The registration itself succeeded with the rest.

HostRegistrationRefusal

4222 — one worker a checked registration left out. code is HOST_WORKER_NOT_ASSIGNED, whatever the reason (unassigned, assigned to another host, retired, of another App, or naming nothing).

Field Argument Type Description
worker String! The worker as the host named it.
code String!

HostRegistrationWorker

1709 — a worker a host can launch: the family it would run as, and its existing worktrees there.

Field Argument Type Description
workerId ID!
worker Worker
family String!
worktrees [String!]!

HostSetup

4222 — what the platform says an App's hosts run: the switch, and the assignments in effect (a retired worker's are left out), by host then worker.

Field Argument Type Description
source HostSetupSource!
assignments [HostWorkerAssignment!]!

HostSweepRun

4233 (S10 of #4229): one run of a host's sweep, as the host reported it.

Field Argument Type Description
id ID!
hostId String!
runId String! The host's own token for the run.
startedAt DateTime!
endedAt DateTime!
mode SweepMode! OBSERVE or APPLY; a sweep in mode OFF records nothing.
planned Int!
applied Int!
skipped Int!
failed Int!
lines [HostSweepRunLine!]! At most 50 lines.
recordedAt DateTime! When the server stored the run.

HostSweepRunLine

4233: one worker's line in a sweep run: the worker as the host named it, what became of it, and a reason code.

Field Argument Type Description
worker String!
outcome SweepRunOutcome!
reason String! A code (capital letters, digits, underscores), never text.

HostWorkerAssignment

4222 — one worker the platform says a host runs (hrn:node:hadronmemory.com:specs:cor:agt:070:01, the change Proposed).

workdir is the name the host knows the worker's working directory by (an Orca worktree name, or a plain directory name for a worker without Git); like every argument a host acts on it is a name token, never a path, a command or a credential (hrn:node:hadronmemory.com:specs:cor:agt:070:03). #4230: family, model, effort and accountProfile are its typed launcher profile, never a command (decision G1); while the App's hostSetupSource is SERVER a worker.start carries the set ones, and the host builds the command from a fixed template for the family.

Field Argument Type Description
id ID!
hostId String!
workerId ID!
worker Worker
workdir String!
family String!
model String
effort String #4230 — the effort the launcher runs the model at, a profile token. Null when unset.
accountProfile String #4230 — the host-local account the launcher runs under, a profile token the host maps to its launcher; never a path or a credential. Null when unset.
createdByUserId ID!
createdAt DateTime!
updatedAt DateTime!

ImpersonationInfo

Admin impersonation (read-only support sessions): the acting-as facts of THIS request's credential, surfaced on AuthContext so whoami-style consumers can name the real actor, the scope org, and the expiry.

Field Argument Type Description
sessionId ID!
actorUser User The admin behind the curtain (visibility per the normal User field rules — the actor is a co-member of the scope org).
organizationId ID!
expiresAt DateTime!
readOnly Boolean! Always true in v1 — impersonated sessions cannot mutate.

ImpersonationSession

One admin-impersonation session: the durable audit record (who impersonated whom, in which org, when) AND the revocation source of truth (stopImpersonation writes endedAt; rows are never deleted).

Field Argument Type Description
id ID!
adminUser User!
targetUser User!
organization Organization!
reason String
createdAt DateTime!
expiresAt DateTime!
endedAt DateTime Explicit-stop timestamp; null while live or when the session merely lapsed by TTL.
endedBy ID User.id of whoever stopped it early (the admin actor for a self-stop from the impersonated context). Null while live / TTL-lapse.
isActive Boolean! Derived: endedAt is null AND expiresAt is in the future.

ImpersonationSessionList

Field Argument Type Description
items [ImpersonationSession!]!
total Int!

ImportNodeResult

Field Argument Type Description
status ImportNodeStatus!
node Node
jobId ID Reserved for the async path — always null in sync v1.

IndexTruncated

Declared successful partial passage indexing (hrn:node:hadronmemory.com:specs:cor:rag:010:01).

Field Argument Type Description
omittedChunks Int! Number of passage chunks not embedded.

InheritedFrom

1885 (hrn:node:hadronmemory.com:specs:cor:dmo:050:14) - the base Agent an

inherited node comes from.

Field Argument Type Description
agentId ID!
agentUrn String! The base Agent's URN, fully qualified.

InstallAgentIntoAppPayload

Return shape for the installAgentIntoApp mutation. Wraps the new AppAgent row so callers can read its audit fields without re-querying.

Field Argument Type Description
appAgent AppAgent!

InstallationPolicy

Field Argument Type Description
maxMembers String! Integer-as-string OR the sentinel 'unlimited'. GraphQL does not have an Int|String union; clients parse: parseInt(maxMembers) succeeds for integer values; 'unlimited' is the sentinel.
memberRoles [String!]!

JoinAppPayload

Return shape for the joinApp mutation (023-app-shape US2). The AppMember row is included so callers can read its derived isOrgExternal flag without a re-query.

Field Argument Type Description
appMember AppMember!

LeaveAppPayload

Return shape for the leaveApp mutation (023-app-shape US2). The user's personal-class Memory at (appId, userId) is NOT cascade-deleted (spec 008 FR-015 orphan retention); it re-attaches if the user later re-joins the same App.

Field Argument Type Description
appId ID!
userId ID!

LiftStopSignalResult

Field Argument Type Description
signal StopSignal!
changed Boolean! False when it had already ended: nothing changed and nobody was told again.

LintWarning

2048 — one link-lint warning. A fixed set of fields: there is no free-form detail.

Field Argument Type Description
kind LintKind!
position Int! 0-based source-tag offset, or immutable occurrence ordinal for compiled-revision lint.
text String!
targetUrn String The target's URN, only for a target the caller can read; null for BROKEN_INCLUDE.
pinnedRevision Int The revision the include pins, when it pins one.
newerRevision Int The newest approved revision, for PINNED_NEWER_APPROVED.
overriddenNodeLoc String Reserved for the policy-agent override notice; null for source lint.
workerField String For WORKER_LINK_MISSING, which stored field lacks the worker link: signature or trailer. Null otherwise.

LintWarningPage

2048 — one page of warnings, ordered by position.

Field Argument Type Description
items [LintWarning!]!
total Int! All warnings that hold, not just this page.
nextCursor String Pass as after for the next page; null on the last.

LocSegment

3456 - one row of memoryLocSegments: a next loc segment under the parent, and the memory it comes from.

Field Argument Type Description
segment String! The next segment name (no colon).
hasNode Boolean! True when an eligible node sits at exactly <parent>:<segment> in this memory; false for a branch that only has nodes below it.
memoryId ID! The memory the row comes from (an inherited system memory names itself).

LocSegmentsPage

3456 - one page of memoryLocSegments.

Field Argument Type Description
items [LocSegment!]!
endCursor String Opaque. Null when hasMore is false.
hasMore Boolean!

MarketplaceResourcePage

A paginated page of sanitized public resource refs (marketplace catalogue).

Field Argument Type Description
items [PublicResourceRef!]!
total Int!

McpServer

One registered EXTERNAL MCP server (hadrontool-mcp conduit registry). Org-owned. Static auth headers are encrypted at rest and WRITE-ONLY: no field here ever returns them — hasHeaders is all a reader gets. The row grants nothing by itself; every run-time call walks the policy chain as 'tool.mcp__<slug>__<tool>' plus the run's action budget.

Field Argument Type Description
id ID!
organizationId String!
slug String! Run-tool name segment (mcp__<slug>__<tool>); lowercase [a-z0-9-], unique per org, immutable.
name String!
url String! Streamable-HTTP MCP endpoint URL.
toolAllowlist [String!]! Exposed-tool allowlist; empty = every tool the server advertises.
hasHeaders Boolean! Whether encrypted static headers are stored (the values are never returned).
enabled Boolean! Disabled servers fail run-tool resolution loud, same as an unregistered slug.
createdAt DateTime!
createdBy String
updatedAt DateTime!
updatedBy String

McpServerTool

One tool an external MCP server advertises, as admitted by the registry row (allowlist + name grammar + length cap applied) — what this query returns IS what a run can declare in data.tools.

Field Argument Type Description
name String! The tool's name on the external server.
description String
runToolName String! The run-tool / policy name: mcp__<slug>__<name>.
inputSchema JSON The tool's argument JSON Schema, passed through verbatim.

McpServersPage

Uniform paginated list shape (cor:api:120).

Field Argument Type Description
items [McpServer!]!
total Int!

MemoriesPage

Field Argument Type Description
items [Memory!]!
total Int!

Memory

A Hadron memory (git repo + branch settings).

Field Argument Type Description
id ID!
organizationId String
organization Organization The owning Organization when the caller may read that Organization; a Memory read alone does not grant it.
urn String! The memory's URN, grammar v2 (cor:urn:010:01): hrn:mem:<root>:<slug...>, emitted by safeCanonicalUrn/emitEntityUrnV2 from the stored urn — so a v1 double-colon chain, a legacy single-colon row and an already-v2 row all read back identically here. <slug...> is one atom for a migrated memory but still several for a compound pre-Stage-3 per-user one (<root>:<agent>:app-user:<id>). The STORED column is the bare form (<root>:<slug>, no scheme prefix — the chk_memory_urn_not_prefixed guardrail rejects writing a rendered one); this field is the rendered view of it. When emission throws, the stored value is served raw and logged, so a bare, unprefixed value is a possible read.
name String!
shortDescription String
description String
data JSON Free-form structured metadata bag (client-defined JSON, no server-side semantics). Null when unset. Settable via createMemory / updateMemory.
schema JSON #725 — opt-in per-memory property schema (declared collections + typed fields). NULL = unstructured. Authored via updateMemory; well-formedness validated server-side.
tags [String!]!
license String
category0 String
category1 String
category2 String
iconUrl String
heroUrl String
homeUrl String
source String
readBranch String
writeBranch String
visibility MemoryVisibility 035-visibility-enum-cleanup: nullable — set only for knowledge/group.
listedOnMarketplace Boolean! cor:acl:080:04 — opt-in marketplace catalogue flag (advertisement, not access).
class MemoryClass! Which memory typology this row belongs to. See MemoryClass for the members — deliberately not restated here, because the count is what went stale: this said "four-way" from 005-agent-subscription until #1232, long after `group` (023) and `private` made it six.
shareable Boolean! #766 — derived shareability signal: true iff this memory can be shared with an individual user via MemoryShare, i.e. class = 'personal' (spec 023 FR-018). Lets the CLI and portal surface or gate the share action before a createMemoryShare attempt rather than discovering InvalidMemoryClassForShareError at execution time.
acceptsUploads Boolean! 006-asset-upload-redesign: per-memory upload-acceptance gate. Default true for app/knowledge/personal-class memories; false for system-class. Org admins or memory owners can flip via the setMemoryAcceptsUploads mutation (added in v2 story phases).
userId ID The strict user owner, for BOTH `personal` and `private` classes — the DB invariant is `class IN ('personal','private') ⇔ user_id IS NOT NULL`, so a private memory has one too. Resolves to null for every other class, and also when the caller is not the memory owner / not ADMIN/OWNER of the memory's org.
isEncrypted Boolean!
vectorIndexEnabled Boolean!
embeddingSource EmbeddingSource!
chunkTokens Int Spec 033 US2 — chunk-window size in tokens (~4 chars/token). Null = platform default (512). Applies when embeddingSource includes content chunks.
chunkOverlap Int Spec 033 US2 — overlap between consecutive chunks in tokens. Null = platform default (64). Must be < chunkTokens.
forceFixedSize Boolean! Spec 033 US2 — force the fixed-size chunking strategy, bypassing the structure-aware default. Useful when the content's heading structure is unreliable (e.g. transcripts, machine-generated reports).
maxRevCount Int! #621 — cap on how many NodeRevision rows are kept per node in this memory. On each new revision the oldest overflow is pruned. Default 10; minimum 1.
corpusState CorpusState! #1447/#1448, derived per node since #1591 — DRAFT while none of this memory's live nodes is minted, MINTED once any is. Draft rights are per node: an unminted node can be renumbered, moved without a URN alias, and bulk-replaced, in any memory (see Node.mintStatus).
corpusMintedAt DateTime #1448/#1591 — the latest mint time among this memory's live nodes; null while none is minted.
vectorIndexEncryptedAckAt DateTime Spec 033 FR-026 — timestamp at which the memory owner accepted the encrypted-memory vector-inversion disclosure. Set when the caller passes acknowledgeVectorInversionRisk: true on updateMemory for an isEncrypted: true memory enabling vectorIndexEnabled for the first time. The portal surfaces this readback so the user can confirm when they accepted the tradeoff (the disclosure text is the FR_026_DISCLOSURE constant in src/lib/entityRef/errors.ts). Survives a revoke + re-enable cycle (never cleared). Null for unencrypted memories and for encrypted memories where the index was never enabled.
userMemoryOfAgentId String
anonymousExpiresAt DateTime
appId ID The App this memory is scoped to. Required for app-class memories. A system-class Agent definition has no App; a system-class INSTALL MEMORY has an App and isInstallMemory=true, including after its Agent link is detached. Other classes (knowledge, group, personal, private) may be App-scoped or free-standing. Enforced by chk_memory_class_app_id.
app App The linked App when the caller may read that App; a Memory read alone does not grant it.
agent Agent Populated only for class = system — the agent this memory is the system memory of. Null for regular knowledge memories.
syncStatus SyncStatus!
syncError String
lastSyncReport String Versioned JSON outcome of the last sync (v1, or v2 when an attestation-refused entry requires it): partial, failed or unknown. Null after a completed clean sync; consult lastSyncedAt/syncStatus for a never-synced memory. Same Memory-record read gate applies. Git sync: hrn:node:hadronmemory.com:specs:cor:int:010:01.
pendingEdgeCount Int!
lastSyncedAt DateTime
createdAt DateTime!
updatedAt DateTime!
subscriptions [MemorySubscription!]!
shares [MemoryShare!]! 023-app-shape US3: cross-user grants on this memory. Non-empty only when class = personal (FR-018). Includes grantee + role for each row. Visible only to the principal (memory.userId) and to ADMIN/OWNER of the memory's owning org.
myShare MemoryShare The caller's OWN share of this memory (they are the grantee), or null. Grantee-readable — unlike shares (principal / org-admin only), this returns at most the single MemoryShare row keyed (memoryId, callerId), so it never leaks co-grantees. null for a non-grantee or an App-key caller. Lets the portal render Shared-by-@grantor + the role on each shared-with-me row.
members [MemoryMember!]! 023-app-shape US4: team membership rows on this memory. Non-empty only when class = group (FR-027). Visible to any current member (any role) and to ADMIN/OWNER of the memory's owning org.
config MemoryConfig #1325 — this memory's config: its node-role rules. Null for anyone who does not MANAGE the memory (the strict owner of a personal/private memory; else its user owner or an org ADMIN/OWNER), however the Memory was reached. A memory with no rules yet reads as the empty config (id null, no rules).

MemoryConfig

1325 — a memory's config: exactly one per memory, holding its node-role

rules (one per role or declared sub-role). Read and changed only by the memory's managers. Materialized by the first rule write; before that it reads as empty, with a null id.

Field Argument Type Description
id ID Null until the first rule is written.
memoryId ID!
rules [NodeRoleRule!]! Role-ascending.
defaultSkips [MemoryConfigDefaultSkip!]! #3426 — org-default rules skipped when this memory was created (a reference deleted, unreadable to the organization or not a task). Managers only, like the config. Proposed addition to hrn:node:hadronmemory.com:specs:cor:api:290.
createdAt DateTime
createdBy ID
updatedAt DateTime
updatedBy ID

MemoryConfigApplyEntry

Field Argument Type Description
role String!
outcome MemoryConfigApplyOutcome!
rule NodeRoleRule The rule in force for this role afterwards. On a dry run, the existing rule, or null for a would-be APPLIED.

MemoryConfigApplyResult

Field Argument Type Description
memoryId ID!
template NodeRoleRuleSourceTemplate!
templateRevision Int! The template revision that was applied; pass it back as expectedTemplateRevision to apply exactly what a dry run showed.
required Boolean!
dryRun Boolean!
entries [MemoryConfigApplyEntry!]! One per template rule, role-ascending.
warnings [MemoryConfigWarning!]! TASK_LESS_VISIBLE for each rule this apply wrote, or on a dry run would write. A dry run and the real apply report the same warnings.

MemoryConfigBulkApplyEntry

Field Argument Type Description
index Int! The position of the ref in memoryRefs; results[i] answers memoryRefs[i].
memoryRef String! Your input string, verbatim. Never a resolved id, name or URN.
ok Boolean!
result MemoryConfigApplyResult Non-null exactly when ok. SKIPPED_CONFLICT and SKIPPED_LOCKED entries are outcomes of a successful apply, so ok stays true.
error MemoryConfigBulkApplyError Non-null exactly when not ok.

MemoryConfigBulkApplyError

Field Argument Type Description
code String! MEMORY_NOT_FOUND (an unknown ref and a memory you cannot manage read byte-identically), DUPLICATE_TARGET, CONFLICT, NODE_NOT_FOUND, NOT_A_TASK, NODE_ROLE_RULE_REF_BROKEN, MEMORY_CONFIG_TEMPLATE_NOT_FOUND, BAD_USER_INPUT, or INTERNAL_SERVER_ERROR.
message String!
currentRevision Int Set only for a CONFLICT on the template revision.
requestId String Set only for INTERNAL_SERVER_ERROR: the id the server log carries for this fault.

MemoryConfigBulkApplyResult

Field Argument Type Description
dryRun Boolean!
results [MemoryConfigBulkApplyEntry!]! One per input position, in input order.
succeeded Int!
failed Int!

MemoryConfigDefaultSkip

3426 — one org-default rule skipped at memory creation. Stores no task URN and no state: ref and refState are the

template rule's reference as the CALLING manager sees it now. Null/BROKEN once the template or rule is gone.

Field Argument Type Description
role String!
field String! authorTask, validationTask or descriptionNode.
reason String! REFERENCE_UNAVAILABLE: deleted, unreadable to the organization, or not a task.
sourceTemplate NodeRoleRuleSourceTemplate
ref String
refState NodeRoleRuleRefState!
createdAt DateTime!

MemoryConfigTemplate

1325 part (c) — a reusable rulebook with exactly one owner, COPIED into a

memory's config when applied (never live-linked). Read and managed only by its owner's managers: a platform admin (server), an org ADMIN/OWNER (organization), the user themselves (user), the App's owner or org ADMIN/OWNER (App). For anyone else it does not exist.

Field Argument Type Description
id ID!
name String! Unique per owner among live templates; 1-64 lower-case letters, digits, '-' or '_'.
description String
required Boolean! Applied as locked rules (#1334).
orgDefault Boolean! #3426 — applied to every new org knowledge/group memory at creation. Always false for a non-organization owner. Proposed addition to hrn:node:hadronmemory.com:specs:cor:api:290.
ownerType MemoryConfigTemplateOwnerType!
ownerId ID ID of the owning organization, user or App; null for the server.
rules [MemoryConfigTemplateRule!]! Role-ascending.
revision Int! Optimistic-concurrency token for the template AND its rules.
createdAt DateTime!
createdBy ID
updatedAt DateTime
updatedBy ID

MemoryConfigTemplatePayload

Field Argument Type Description
template MemoryConfigTemplate!
warnings [MemoryConfigWarning!]! Always empty for a template save: less-visible-task warnings are computed when a template is applied to a memory (there is no target memory here).

MemoryConfigTemplateRule

1325 part (c) — one rule of a template: a node-role rule without the config-only fields.

Field Argument Type Description
role String!
authorTask String
authorTaskId ID
authorTaskState NodeRoleRuleRefState!
validationTask String
validationTaskId ID
validationTaskState NodeRoleRuleRefState!
descriptionNode String Documentation, not procedure: a deleted description node reads as NONE, never BROKEN.
descriptionNodeId ID
descriptionNodeState NodeRoleRuleRefState!
strictSubRoles Boolean!
writers NodeRoleWriters!
validateBy ContentValidator
enabled Boolean!

MemoryConfigTemplatesPage

Field Argument Type Description
items [MemoryConfigTemplate!]!
total Int!

MemoryConfigWarning

1325 — a non-fatal finding about a saved rule. Never changes the mutation's success. Today the only code is TASK_LESS_VISIBLE (#1327): a task the saver can read that some reader of the memory may not; taskUrn and taskState are the saver's own reference projection, so a task the saver cannot read is named by state alone. It is also what a save answers when that check could not be completed after the rule was saved (containment not established, not proof that a reader is missing): the save still succeeds, and taskUrn and taskState are then null when the saver's own projection was unavailable. An App write or automation read grant on the memory counts as a reader that cannot be proven to read the task.

Field Argument Type Description
code String!
role String!
field String
taskUrn String
taskState NodeRoleRuleRefState

MemoryIntegrityReport

1591 — the tamper check over every live node of a memory.

Field Argument Type Description
checked Int!
intact Int!
tampered Int!
superseded Int!
notApproved Int!
problems [NodeIntegrityCheck!]! Every node that is not INTACT, ordered by loc.

MemoryMember

023-app-shape US4: symmetric team-membership row for group-class memory. The "Company Brain" model — multiple users collaboratively read/write a shared memory, governance by role, no single owner on the Memory itself.

Field Argument Type Description
memory Memory #2509: this memory's record, exactly as Query.memory answers it to the caller, or null when the caller may not read that record (or it is deleted). Seeing this membership does not grant its memory's record, so use memoryId for the address.
user User!
role MemoryMemberRole!
createdAt DateTime!
createdBy String
updatedAt DateTime
updatedBy String

MemoryOwnerTransferPreview

Field Argument Type Description
memoryId ID!
oldUrn String!
newUrn String!
fromOwner ID!
toOwner ID!
currentClass MemoryClass!
targetClass MemoryClass!
dependents [MemoryTransferDependent!]!
blockers [MemoryTransferBlocker!]!
canApply Boolean!
applied Boolean!

MemoryProvisioning

Field Argument Type Description
appMemory AppMemoryKind!

MemoryShare

023-app-shape US3: asymmetric cross-user grant on a personal-class Memory. The principal (memory.userId) grants a grantee read/write access. Used for per-pairing isolation patterns (e.g., Alice's personal Memory paired-with-Mentor-A is distinct from her paired-with-Mentor-B Memory, each with its own MemoryShare).

Field Argument Type Description
memory Memory #2509: this memory's record, exactly as Query.memory answers it to the caller, or null when the caller may not read that record (or it is deleted). Seeing this share does not grant its memory's record, so use memoryId for the address.
grantee User! The User who was granted access.
grantor User! The principal of the Memory (Memory.userId). Per spec 023 FR-019 this is always the principal, even when an App backend made the API call on the principal's behalf — that actor is recorded in createdBy instead.
role MemoryShareRole!
createdAt DateTime!
createdBy String The API actor who created the row. Distinct from grantor when an App backend creates the share on the principal's behalf.
updatedAt DateTime
updatedBy String

MemorySubscription

An organization's subscription to a memory it does not own.

Field Argument Type Description
id ID!
memory Memory!
organization Organization The subscriber Organization when the caller may read it; memory access alone does not authorize it.
role Role!
activated Boolean!
createdAt DateTime!

MemoryTransferBlocker

Field Argument Type Description
code String!
message String!

MemoryTransferDependent

Field Argument Type Description
kind String!
count Int!
handling MemoryTransferHandling!

MemoryValidationFinding

One finding (#819). nodeUrn is null when the URN could not be composed - a memory URN the flat v2 shape cannot express, or an unexpected/legacy loc - in which case nodeId and nodeLoc still identify the node.

Field Argument Type Description
kind MemoryValidationCheck!
nodeId ID!
nodeLoc String!
nodeUrn String
detail String!

MemoryValidationResult

Field Argument Type Description
memoryId ID!
nodesChecked Int! Live (non-deleted) nodes scanned - soft-deleted tombstones are excluded, since their findings would be unactionable (#884). The whole memory in one pass - the checks are cross-referential, so a partial scan would produce false positives rather than fewer findings.
findings [MemoryValidationFinding!]! Findings, capped by the limit argument, with problems before informational declarations.
totalFindings Int! The TRUE problem count, before any truncation. Excludes informational INDEX_TRUNCATED. Gate health and CI on ok, which also accounts for skipped checks.
totalInformational Int! The TRUE informational declaration count, before any truncation. Does not affect health.
truncated Boolean! True when findings was capped and totalFindings + totalInformational is larger.
skippedChecks [MemoryValidationSkippedCheck!]!
ok Boolean! True only when EVERY check ran and none found a problem. INDEX_TRUNCATED is informational and does not make this false. A skipped check makes this false even with zero findings - you cannot claim health for a check you did not run.

MemoryValidationSkippedCheck

A check that could NOT run (#819). Reported explicitly rather than silently omitted: a clean bill of health that quietly skipped a check is worse than no report at all.

Field Argument Type Description
check MemoryValidationCheck!
reason String!

ModelFamilyAvailability

1706 — one model family's availability for work in one App (hrn:node:hadronmemory.com:specs:cor:agt:060:03). A family with no record is available.

Field Argument Type Description
appId ID!
family String! The model family, e.g. claude or codex (hrn:node:hadronmemory.com:specs:cor:agt:060:04).
state AvailabilityState!
reason AvailabilityReason
until DateTime
setAt DateTime!
setBy AgentTaskParty
inEffect Boolean! Unavailable and not lapsed.

ModelGroup

2831 - one model group: a lowercase name over a list of lowercase model patterns.

Field Argument Type Description
name String!
patterns [String!]!
updatedAt DateTime!

Node

Field Argument Type Description
deletedAt DateTime Deletion marker. Ordinary reads still omit tombstones; explicit recovery is writer-only.
id ID!
moveLinkWarnings [NodeMoveLinkWarning!] #1392 — warnings from a cross-memory move. Null on other Node reads; [] when a move changes no local content links. Raw content is preserved.
revision Int! #1323 — current live revision. Creation is revision 1; each committed authoring change advances it. NodeRevision.revNo N is the retained snapshot of this node when revision N was current, before the edit that advanced it.
authorship NodeAuthorship #1326 — attribution of this content state. Null means legacy or unknown. Task identity is redacted unless its memory is independently readable.
contentValidation NodeContentValidationStatus! #1326 — advisory validation for this exact revision. A report for an older revision is STALE.
validationTasks NodeValidationTaskSet #3659 (hrn:node:hadronmemory.com:specs:cor:dmo:160:01) — the validation tasks a content-validation report for this node may name now, as the recorder judges them for this caller. Null on an inherited, install-concealed or deleted node, or one whose memory fails the node-content gate.
approvalStatus NodeApprovalStatus! #1591 — whether the current revision is approved, and the latest approval on record.
mintStatus NodeMintStatus! #1591 — whether this node is minted, and the record of it.
lintWarnings LintWarningPage #2048 (hrn:node:hadronmemory.com:specs:cor:agt:040:13) — link lint for a boot-prompt source: the warnings that hold for this node as it is now, read as the caller (a target the caller cannot read is a position-only BROKEN_INCLUDE). An empty page is a real answer; null means the warnings are unavailable (a fault, or a compiled boot prompt, whose warnings read its recorded provenance). Lint never blocks a write, and nothing is stored or pushed. Pages default to 50 and clamp at 100.
first Int
after String
signatureStatus NodeSignatureStatus! #1632 (hrn:node:hadronmemory.com:specs:cor:dmo:130:06) — the node's signatures and their derived states, current signers first. Batch-loaded on list and search reads. An encrypted node reads NOT_APPLICABLE and lists none.
signingRequests ⚠️ [SigningRequest!]! #1632 (hrn:node:hadronmemory.com:specs:cor:dmo:130:03) — the node's signing requests, newest first, including ended ones (#10019). state filters on the effective state (an open request past its deadline is EXPIRED). first: 1–100, default 20.

⚠️ DEPRECATED

Use signingRequestsPage for hasMore and nextCursor.
state SigningRequestState
first Int
signingRequestsPage SigningRequestsPage! The node's signing requests with the same reader gate; effective-state filtering precedes paging. Newest first (createdAt, id descending). Default 20, clamp 1–100; after is an authenticated filter-scoped keyset (createdAt, id), valid after deletion of the boundary row. offset is an alternative, never combined with after. total counts the full current filtered set. hrn:node:hadronmemory.com:specs:cor:api:120:04; hrn:node:hadronmemory.com:specs:cor:api:120:05.
state SigningRequestState
first Int
after String
offset Int
createdByWorker ActorRef #1610 — the Worker that created this node, when it was written in a worker session. The user is createdBy. Null for a write with no worker behind it, and for nodes written before #1610.
createdByAgent ActorRef #1610 — the Agent behind this node's creation: a worker's role agent, an agent session, or a headless App run. Null when no agent was behind it.
updatedByWorker ActorRef #1610 — the Worker behind the last authored edit. A later authored edit with no worker behind it clears it, so it always describes the last authored edit (not the updatedAt clock, which operational writes also advance).
updatedByAgent ActorRef #1610 — the Agent behind the last authored edit; cleared like updatedByWorker.
updatedByUser NodeRevisionEditor #2176 - the User behind the last authored edit, as handle and URN only (the same projection as a revision's editedByUser, and always the user that revision records). Cleared like updatedByWorker: an authored edit with no user behind it (a system job, a git sync, an API key with no account) clears it. Null also for a deleted user and for nodes last edited before #2176, which are not backfilled.
createdByUser NodeRevisionEditor #1151 - the User behind this node's creation, as handle and URN only (the same projection as updatedByUser). Null when the stored creator resolves to no live user (a system job, an app key, a deleted user; the stored value is never echoed), and for nodes written before the column was stamped, which are not backfilled.
commentSummary CommentSummary! #1606 — open and resolved discussion on this node (hrn:node:hadronmemory.com:specs:cor:dmo:110:07). Batched per request.
asComment Comment #1608 — this node AS a comment (author, target, anchor revision, thread) when its nodeType is 'comment'; null for content. Lets a search hit render as feedback, never as content of its target (hrn:node:hadronmemory.com:specs:cor:dmo:110:08).
memoryId String!
nodeType String! The PLATFORM-kind axis (info / task / prompt / record / …). Load-bearing for retrieval and rendering. NOT 'objectType', which says which domain COLLECTION a node belongs to, and NOT 'role', which says what the node is FOR. Three kind-ish fields is the accepted price of keeping retrieval stable while roles stay open, so each one says what it is not — mixing them up is the predictable failure.
objectType String #725 — the COLLECTION discriminator: which domain object this node is an instance of, e.g. "competitor" / "insight". Validated against the memory's property schema when it has one. NULL for an ordinary node. NOT 'nodeType' (the platform-kind axis, which drives retrieval) and NOT 'role' (what the node is for; role can be filtered explicitly but does not change default ranking or rendering).
loc String!
urn String! Fully-qualified node URN (hrn:node:<root>:<memory>:<loc>), composed server-side from the node's memory URN + loc (#481). Carried by every Node-returning surface (findNodes, node, appNodes, nodeBatch, mutation returns).
portalUrl String #881 — the portal URL that opens this node, built server-side so no client ever has to construct one (constructing means guessing which URN spelling the /app/u/<urn> route resolves, and the legacy '::' forms in circulation make that guess wrong). Form: <portal-origin>/app/u/<urn>, the portal's stable URN-alias route. NULL when the deployment has no portal origin configured (FRONTEND_URL) — a link to the wrong host is worse than none, so clients render the field only when present.
actionUrn String #2610 — this node's action URN (hrn:action:<root>:<agent-slug>:<code>, the action-register address) when it is a register:<code> entry in an Agent's system memory; null for every other node (a register: loc in a non-Agent memory names no entry). Computed on read from the holding Agent's own URN — never stored — and a second address beside urn: the node URN keeps resolving. An unemittable stored code atom (charset/length) also reads as null; the stored loc needs repair. Two deliberate asymmetries with resolveUrn's action arm (PR #2711 §10 review): (1) this field computes for ANY caller who can read the node — including an App participant of an install — while the arm resolves only under the agent arm's gate, so such a caller can SEE an address that does not resolve FOR them (it resolves for the Agent's own tenant); the field leaks nothing the node read didn't already grant. (2) After an Agent rename this field shows the CURRENT slug (computed from the live Agent's urn) while the urn field still shows the stored node URN until alias healing catches up — the computed address is the fresher one on purpose.
inheritedFrom InheritedFrom #1885 (hrn:node:hadronmemory.com:specs:cor:dmo:050:14) - set when this node was read through an Agent that extends a base: the node belongs to that base's system memory and comes into the Agent's effective system memory by inheritance. The node keeps its own address (its urn is the base's); this names the base it comes from. Null for a node read in its own memory.
isPlaceholder Boolean! #1450 — a server-recorded placeholder awaiting authored content, such as a RESERVED spec citation created by reserveSpecCitation. A placeholder may exist in any memory; it is never inferred from an empty body. Writing real nonblank content through the spec door or shared mirror write path clears it. Placeholders block minting.
isLink Boolean!
name String!
alias String
description String
abstract String Paragraph-length summary of this node. Opt-in on hadron_get_node via the contentScope parameter. hadron_find_nodes preview surfacing ships in spec 031 US2 — not yet live. Never surfaced in hadron_list_nodes. Cap is 2000 characters; longer values are rejected with NodeAbstractTooLongError. Empty + whitespace-only values normalize to null. Spec 031.
abstractOriginHash String Spec 032 — fingerprint of the content value at the time abstract was authored. SHA-256 of plaintext content, truncated to 8 hex chars. Compared at read time against computeContentHash(node.content) to detect staleness: the abstract may not reflect current content when the two differ, OR when this is NULL on a node that has both an abstract and content (#1128 — an abstract written before the body existed was never fingerprinted, so it has never been checked against it; that reads as unverified, not as verified). NULL is only a clean state when the node has no abstract, or no content for the abstract to describe. Note restoreNodeRevision restores this field verbatim, so restoring a snapshot taken while it was NULL reinstates the unverified state — correctly, since that abstract has never been checked against the restored content. System-managed; never settable via NodeInput.
embeddingPendingAt DateTime Spec 033 FR-006/FR-007 — set when this node needs (re-)embedding; cleared on success. The single work signal the embedding worker drains. A FUTURE-dated value is a backed-off retry not yet due (#882) — the worker only selects stamps at or before now. Operational state (never versioned on NodeRevision). The portal renders this as a subtle "embedding…" badge so a user who just edited isn't confused that their change "didn't take" in search yet. System-managed.
embeddingFailedAt DateTime Spec 033 FR-009 — set when an embed attempt failed (record, not a work signal). Retryable failures (timeouts, 5xx) reschedule with exponential backoff and never give up (#882); permanent failures (deterministic 4xx, dimension mismatch, encrypted-no-plaintext) clear embeddingPendingAt — recovery is the retryFailedEmbeddings mutation. The portal renders this as a red badge with the embeddingError message inline so users with an empty index can distinguish "nothing matched" from "every embed failed". System-managed.
embeddingError String Spec 033 — last embed error message (diagnosability; also surfaced by hadron_validate). Common values: encrypted-no-plaintext (#206), embedding-endpoint-unreachable, dimension-mismatch. Null when no failure has been recorded since the most recent success or revoke. System-managed.
embeddingAttempts Int! Spec 033 — attempt counter feeding the exponential-backoff schedule (#882 — no terminal give-up; a retryable failure never removes the node from the queue). Resets to 0 on success or revoke. Surfaced for ops diagnostics (a node at a high attempt count is retrying at the backoff ceiling and likely needs operator attention). System-managed.
indexTruncated IndexTruncated Passages omitted by the per-node indexing cap; null when not truncated (hrn:node:hadronmemory.com:specs:cor:rag:010:01).
content String The node's text. Include tags and data variables resolve for the reader (hrn:node:hadronmemory.com:specs:cor:dmo:150:03); pass raw: true for the stored text with its tags as written. Through nodeBatch, an omitted raw returns the stored text permanently (R21 A) and raw: false resolves.
raw Boolean
tokens Int
tags [String!]!
properties JSON
data JSON
seq Int
ownerRepo String
isRunnable Boolean Whether this node can be run as a task (nullable; #513) — it drives the tree action indicator, and since #1201 it is also the CAPABILITY gate for the task kind: a write that would PRODUCE a runnable node must come through createTaskNode / updateTaskNode. Gated here rather than on a label because omitting a label is free, while omitting this means the node does not run.
role String #1201 — what this node is FOR, as an OPEN string. A closed governed subset has dedicated authoring doors; memory role rules can additionally constrain arbitrary roles. NOT 'nodeType' (the platform-kind axis, load-bearing for retrieval) and NOT 'objectType' (the collection discriminator, schema-validated). This field does not change default retrieval or ranking; NodeFilter.role explicitly selects its exact dotted family (#1322). A GOVERNED family routes the write to that kind's own authoring door, and the generic node surface is refused: 'review' / 'review.*' and 'spec' / 'spec.*' and 'decision' / 'decision.*', alongside the task kind, which is gated on 'isRunnable' rather than on any label because a label can be omitted and a capability cannot. Other roles do not invoke a governed door, but can still be constrained by memory role rules and selected by explicit role filters.
llmModel String
aiAgent String
createdAt DateTime!
updatedAt DateTime!
memory Memory #2193: this node's memory record, exactly as Query.memory answers it to the caller, or null when the caller may not read that record (or it is deleted). Seeing a node does not grant its memory's record, so use urn or memoryId for the address. Always null on an inherited node.
outgoingEdges [Edge!]!
incomingEdges [Edge!]!
asset Asset The asset this node references, for a reference node created by createAssetReferenceNode or hadron_store_file (its data.asset points at one). Null for every ordinary node. Also null when the pointer is DANGLING — the asset was deleted, or is soft-deleted. There is no schema-level Asset-to-Node foreign key (cor:dmo:060:10 reserves it), so data.asset.id is a soft reference and this resolver is what keeps it honest: never assume a node carrying data.asset still has a live asset behind it.

NodeApproval

1591 — one recorded approval of a node revision.

Field Argument Type Description
revision Int! The approved revision number (Node.revision at approval time).
approvedBy NodeRevisionEditor The approving user's public identifiers; null when the approver was not a user (see approvedByInfo).
approvedByInfo String The approving principal when no user is known, e.g. app:<id>.
approvedAt DateTime!
hash String! Approval hash v1 at approval time: 64 lowercase hex of SHA-256 over the canonical title/abstract/content serialization (src/lib/approvalHash.ts).

NodeApprovalReceipt

1591 — a node and its approval, returned by the approve mutations.

Field Argument Type Description
nodeId ID!
urn String!
loc String!
approval NodeApproval!
lintWarnings LintWarningPage #2048 — the link-lint warnings for this node as they hold now; the same data as Node.lintWarnings. Approving never blocks on a warning.
first Int
after String

NodeApprovalStatus

1591 — a node's approval state plus its latest approval.

Field Argument Type Description
state NodeApprovalState!
approval NodeApproval The latest approval on record; null when NOT_APPROVED or NOT_APPLICABLE.

NodeAuthorship

Field Argument Type Description
kind NodeAuthorshipKind!
taskRef String
taskRevision Int
human NodeRevisionEditor
authoredAt DateTime!

NodeBatchResult

Spec cor:api:040 — result envelope for the batch node read (nodeBatch). 'nodes' is the authorized, existing subset (input order for a ref set, loc order for a prefix). 'unavailable' and 'omitted' are both lists of REFS, not node objects. 'unavailable' lists the requested refs that were denied OR not found — indistinguishable, so the result never discloses whether an unreadable node exists. 'truncated' is true when the response-size cap was reached, and 'omitted' then carries the refs of the nodes dropped to stay under it. (Over the node-count cap the query errors instead — never a silent short read.) Both lists echo the caller's OWN ref strings for the 'refs' form — pass a URN, get that URN back, not a primary key you never sent — and node ids for the prefix form, which has no caller refs.

Field Argument Type Description
nodes [Node!]!
unavailable [ID!]!
truncated Boolean!
omitted [ID!]!

NodeContentValidationReport

Field Argument Type Description
nodeRevision Int!
validationTaskRef String
validationTaskRevision Int
outcome NodeContentValidationOutcome!
reportedAt DateTime!
authorCheck NodeContentValidationAuthorCheck #1332 — the author check made when the report was recorded. Null on a report recorded before #1332.

NodeContentValidationReportReceipt

1332 — the answer of recordNodeContentValidationReport.

Field Argument Type Description
nodeId ID! The node the report is about.
replayed Boolean! True when an earlier report with the same runId, from the same reporter, for the same node revision and task revision, was returned and nothing was written.
report NodeContentValidationReport!
state NodeContentValidationState! The validation state of the node's current revision after this call. A report for an older revision is stored as history without changing the current revision's state, including an existing PASS.

NodeContentValidationStatus

Field Argument Type Description
state NodeContentValidationState!
latestReport NodeContentValidationReport

NodeEdgeRemoval

2517 — one edge a hard delete removed from this node (hrn:node:hadronmemory.com:specs:cor:dmo:010:04). The deleted target's address (targetLoc) and the removed edge's loc, which is derived from it, are shown only when you can read the memory the target lived in. Entries are gated per entry by the memory the source was in when the edge was removed. A derived include edge is not recorded.

Field Argument Type Description
id ID!
edgeLoc String The removed edge's loc; null when the deleted target's memory is not one you can read (the loc is derived from the target's address).
edgeName String
targetId ID! Stable id of the deleted target; the row itself is gone.
targetLoc String The deleted target's loc; null when its memory is not one you can read (a cross-memory edge).
reason String! TARGET_HARD_DELETED: the edge's target was hard-deleted.
removedBy String Who deleted: the same user, app or client id a soft delete stamps as deletedBy; null when unattributed.
createdAt DateTime!

NodeExportResult

Field Argument Type Description
format NodeExportFormat!
mimeType String! MIME type, e.g. text/markdown or application/json.
filename String! Suggested download filename, e.g. <loc-leaf>.md.
encoding NodeExportEncoding!
data String! The rendered file contents (TEXT).
bytes Int! Byte length of the rendered payload (UTF-8).

NodeHit

A scored node hit (cor:api:090:04). score is null for an unscored filtered list (no query).

Field Argument Type Description
node Node!
score Float
vector NodeVectorMeta

NodeIntegrityCheck

1591 — one node's tamper check.

Field Argument Type Description
nodeId ID!
urn String!
loc String!
state NodeIntegrityState!
revision Int! The current revision.
approvedRevision Int
expectedHash String The approval hash on record.
actualHash String! The approval hash recomputed from the current title/abstract/content.

NodeMintStatus

1591 — whether a node is minted, and the record of it. Encrypted memories read not-minted with all record fields null; not-applicable is distinguished by approvalStatus. Minting protects nothing by itself (permanence is off for now).

Field Argument Type Description
minted Boolean!
mintedAt DateTime
mintedBy NodeRevisionEditor The minting user's public identifiers; null when not a user (see mintedByInfo).
mintedByInfo String The minting principal when no user is known, e.g. app:<id>, or backfill for nodes minted by the #1591 migration.
revision Int The revision that was minted. Null for nodes backfilled as minted, whose minted revision is unknown.
hash String The approval hash of the minted revision. Null for backfilled nodes, which were never approved.

NodeMoveLinkWarning

Field Argument Type Description
nodeId ID!
nodeLoc String!
raw String!
target String!
status NodeMoveLinkStatus! RETARGETED names a different node; AMBIGUOUS has multiple live alias claimants.

NodeMovePlan

Point-in-time node-only move plan. Reserves nothing; a later move can raise CONFLICT (hrn:node:hadronmemory.com:specs:cor:api:190:03).

Field Argument Type Description
nodes [NodeMovePlanEntry!]!
totalCount Int!
truncated Boolean!
linkWarnings [NodeMoveLinkWarning!] Null when withheld because the destination is unreadable (ruling 0211).
linkWarningsWithheld Boolean!
pointInTime Boolean!

NodeMovePlanEntry

A node's stable identity and planned addresses (hrn:node:hadronmemory.com:specs:cor:api:190:03).

Field Argument Type Description
id ID!
currentUrn String!
newUrn String!

NodePage

2212 A2 — one page of the nodes in an App's scope, counted over the same filter and scope.

Field Argument Type Description
items [Node!]!
total Int!
hasMore Boolean!

NodeRevision

Field Argument Type Description
id ID!
editedByWorker ActorRef #1610 — the Worker behind the edit this snapshot records, beside editedBy (the user).
editedByAgent ActorRef #1610 — the Agent behind the edit this snapshot records.
authorship NodeAuthorship #1326 — attribution of the content captured before the next edit.
contentValidation NodeContentValidationStatus! #1326 — advisory validation at this historical revision.
urn String Computed end-anchored URN hrn:noderev:<root>:<mem>:<loc...>:<rev> (#696). Null for legacy rows without a revNo, and for multi-segment per-user memories the flat shape cannot express.
revNo Int Per-node monotonic revision number (#696). Null on legacy rows predating the counter (backfilled by the migration).
nodeId String!
loc String!
name String!
alias String
description String
abstract String Paragraph summary at capture (spec 031).
content String
tags [String!]!
nodeType String #620: full curated-subset snapshot fields. Null on LEGACY rows captured before the columns existed (nodeType doubles as the legacy sentinel — it is non-null on every post-#620 snapshot).
isLink Boolean
properties JSON
data JSON
seq Int
isRunnable Boolean
role String #1201 — Node.role at capture time. In the curated subset because CLEARING a governed role is the escalation #1202 exists for: a history that cannot show the role cannot show the un-governing.
llmModel String
aiAgent String
editedBy String The editing User id, when a user is known (#620). Use editedByUser for resolution.
editedByInfo String What is known about the editor when no User id is available (#620): 'github:<login>' / 'email:<addr>' / 'user:<id>' identity strings, or 'app:<App.id>' for App-key principals. (Legacy free-form #88 reasons / commit messages that squatted in editedBy were migrated to revLabel.)
editedByUser NodeRevisionEditor The editor resolved to a user (handle + URN) — from editedBy as a User id, the createdBy fallback (#619), or an identity-string form of editedByInfo ('github:<login>' resolves via the user's linked GitHub username). Null when nothing resolves — the portal falls back to the raw strings. Public identifiers only (#617).
revLabel String User-settable label for this revision (#620, 500-char cap) — set via updateNodeRevision; also captures the 'reason' supplied with the edit that took this snapshot (legacy reasons were migrated here).
changes [String!]! Which node fields the edit that took this snapshot changed, e.g. ["abstract","tags"] (#620). The snapshot is the PRE-edit state, so this describes the delta between this snapshot and the state that replaced it. Empty for legacy rows.
approvedBy String User id recorded by per-node approval for this revision; null when no user approval was recorded.
approvedByUser NodeRevisionEditor approvedBy resolved to public identifiers (handle + URN), like editedByUser.
approvedByInfo String #1591 — the approving principal when no user is known, e.g. app:<id>.
approvedAt DateTime #1591 — when this revision was approved; null unless it was approved before it was edited away.
approvalHash String #1591 — approval hash v1 recorded when this revision was approved.
revisionApproval RevisionApproval! #1838 — was THIS revision approved (for pinning)? Not whether the node is approved now (that is Node.approvalStatus). A revision counts as approved when some recorded approval covers exactly its hashed content, whichever revision the approval was recorded on (Holger's R7, hrn:node:hadronmemory.com:specs:cor:dmo:060:04).
createdAt DateTime!

NodeRevisionEditor

A revision's editor resolved to PUBLIC IDENTIFIERS ONLY (#617). Deliberately excludes name / email / any PII — resolving editedBy must never widen the disclosure surface. handle + urn are the same public identifiers the users search already exposes, so no per-caller visibility gate applies.

Field Argument Type Description
handle String
urn String

NodeRevisionPage

2212 — one page of a node's revision snapshots, counted over the snapshots the caller may read.

Field Argument Type Description
items [NodeRevision!]!
total Int!
hasMore Boolean!

NodeRoleRule

1325 — one node-role rule. Task and description references are stored by

node id (they survive moves) and returned as a URN and an id, each with its state. Both are given only when the state is OK; see NodeRoleRuleRefState.

Field Argument Type Description
id ID! The rule's id — its ref for updateNodeRoleRule / deleteNodeRoleRule (a rule has no URN).
role String! The dotted role or sub-role this rule governs, unique within the config.
authorTask String
authorTaskId ID
authorTaskState NodeRoleRuleRefState!
validationTask String
validationTaskId ID
validationTaskState NodeRoleRuleRefState!
descriptionNode String Documentation, not procedure: a deleted description node reads as NONE, never BROKEN.
descriptionNodeId ID
descriptionNodeState NodeRoleRuleRefState!
strictSubRoles Boolean! On a parent role: refuse its undeclared sub-roles instead of falling back to it.
writers NodeRoleWriters!
validateBy ContentValidator
enabled Boolean!
locked Boolean! Set by applying a required template (#1334). A locked rule refuses every ordinary edit and delete (RULE_LOCKED); unlockNodeRoleRule is the deliberate step.
sourceTemplateId ID The template this rule was copied from, if any (provenance only; no live link).
sourceTemplate NodeRoleRuleSourceTemplate
revision Int! Optimistic-concurrency token: pass it as expectedRevision to update or delete.
createdAt DateTime!
createdBy ID
updatedAt DateTime
updatedBy ID

NodeRoleRulePayload

Field Argument Type Description
rule NodeRoleRule!
warnings [MemoryConfigWarning!]! TASK_LESS_VISIBLE for each task reference of the saved rule that a reader of this memory may not be able to read. Advisory: it never changes the save. Empty for unlock.

NodeRoleRuleSourceTemplate

Field Argument Type Description
id ID!
name String!
deleted Boolean! The template has been deleted; the rule keeps its copy.

NodeSignature

1632 (hrn:node:hadronmemory.com:specs:cor:dmo:130:06, hrn:node:hadronmemory.com:specs:cor:dmo:130:07) — one signature on a node. Only the passkey's label is ever shown.

Field Argument Type Description
id ID!
signer NodeRevisionEditor
passkeyLabel String!
passkeyRevokedAt DateTime When the signer's passkey was revoked, if it was; the signature keeps its state.
revision Int! The revision it was made on.
verifiedAt DateTime!
signingRequestId ID!
payloadVersion String!
state SignatureState!

NodeSignatureStatus

1632 — a node's signatures.

Field Argument Type Description
state SignatureState CURRENT if any signature is current, else the best of PENDING, EARLIER, CANCELLED; NOT_APPLICABLE on an encrypted node; null with no signatures.
signatures [NodeSignature!]! Current signers first, then newest first.
integrityProblems Int! Records that fail re-verification: reported, never listed as signatures.

NodeValidationTaskEntry

3659 — one task a report may name, or one broken rule. A broken entry has every other field null.

Field Argument Type Description
broken Boolean!
taskId ID
taskRef String The canonical node URN. A report may name this or taskId.
revision Int The task's current revision, the newest a report may name.

NodeValidationTaskSet

Field Argument Type Description
state NodeValidationTaskSetState!
tasks [NodeValidationTaskEntry!]!

NodeVectorMeta

Per-hit vector-retrieval lineage (cor:api:090:04), present when a hit came from the vector index.

Field Argument Type Description
similarity Float
model String
chunkIndex Int
offsets [Int!]
abstractStale Boolean
source String

ObjectList

745 — a page of objects from the object store. Each object is a flat JSON

record { id, type, ...fields } (the projection of a node). 'total' is the full match count (null when unbounded).

Field Argument Type Description
objects [JSON!]!
total Int

OrgBootPromptSigning

2973 PR2 / hrn:node:hadronmemory.com:specs:cor:agt:040:09: where an organisation stands on requiring a SIGNED compiled

boot prompt. required is the stored switch; enforced is what is true: the switch AND the deployment shipping signing (PASSKEY_SIGNING_ENABLED), so an organisation never reads as protected on a deployment where it is not. deploymentSigns is the second term alone. Readable by the organisation's current ADMINs and OWNERs, acting as themselves.

Field Argument Type Description
required Boolean!
enforced Boolean!
deploymentSigns Boolean!

OrgMember

Per-organization membership record for a user.

Field Argument Type Description
id ID!
user User!
role Role Target member's role in this org. Null when the viewer isn't an ADMIN/OWNER of the org (#384 field-level visibility); always visible for one's own membership.
canInvite Boolean!
createdAt DateTime!

Organization

A company or team that owns one or more Hadron memories.

Field Argument Type Description
id ID!
name String!
urn String!
policy JSON Org-layer action-policy link (cor:acl:040:02, #510). Null = no restriction. Org-admin-authored via updateOrganization.
listedOnMarketplace Boolean! cor:acl:080:04 — opt-in marketplace catalogue flag (advertisement, not access).
githubInstallationId Int
githubAppId String
hasGithubAppPrivateKey Boolean!
members [OrgMember!]!
memories [Memory!]!
agents [Agent!]!
apps [App!]!
subscriptions [MemorySubscription!]!
exchangeConnections [ExchangeConnection!]!
agentOrgGrants [AgentOrgGrant!]! 008-agent-installation: this org's grants for using/bundling Agents. Resolvable to ADMIN/OWNER of the org only.
createdAt DateTime!
updatedAt DateTime!

OrganizationsPage

Field Argument Type Description
items [Organization!]!
total Int!

OwnTeamChatReadState

1353 — the exact Worker/Channel cursor advanced by markOwnTeamChatRead.

Field Argument Type Description
workerId ID!
channelId ID!
lastSeenSeq Int!
channelIncarnation Int! #2181 — the Channel's CURRENT incarnation (with expectedIncarnation, the value that was fenced).
cursorIncarnation Int #2181 — the incarnation the stored cursor was last raised under; NULL is a legacy cursor. See ChannelReadState.cursorIncarnation.

Passage

Spec 033 US2 — one matching chunk from a content-chunk vector index. Carries the locator metadata a RAG consumer needs for context-stuffing: span text, character offset within the parent node, chunk index, and the parent node's URN.

Field Argument Type Description
parentNodeId ID!
parentNodeUrn String!
chunkIndex Int!
charStart Int!
charEnd Int!
text String!
score Float!

PasskeyCancelRecord

Field Argument Type Description
at DateTime!

PasskeyCredential

1631: a passkey record, as its owner sees it. Never a private key.

Field Argument Type Description
id ID!
label String! The owner's name for it; the fixed text "Erased passkey" once the owner's account is deleted.
transports [String!]!
backupEligible Boolean!
backedUp Boolean!
registeredAt DateTime!
lastUsedAt DateTime
revokedAt DateTime
window PasskeyWindow A first passkey's cooling-off window; null for a later passkey.
cancel PasskeyCancelRecord When its cancel link was used; null if never cancelled. The cancel IP address and user agent, and the credential id, are shown only on the interactive revocation page after the owner proves who they are, never over a bearer credential (#1631 PR3 §10).

PasskeyWindow

Field Argument Type Description
endsAt DateTime!
endedAt DateTime
outcome String ran-out | ended-early | cancelled, or null while open (a window that ran out reads by its end time).
registrationMethod String The fresh sign-in method it was registered with.

PolicyLayerVerdict

One layer's verdict in an explained policy evaluation (#510).

Field Argument Type Description
layer String! org, user, or app.
present Boolean! Whether this layer has a link at all (absent = no restriction).
allowed Boolean!
allow [String!] The layer's allow-list, for display; null when absent.

PrProtocolAction

3448 — register guidance for the committed event code (hrn:node:hadronmemory.com:specs:cor:agt:110:03). A caller without an Agent gets WITHHELD and the code only, with no register lookup.

Field Argument Type Description
code String!
state TickActionState!
taskLoc String
taskUrn String

PrProtocolResult

3448 — a command committed, with optional register guidance (hrn:node:hadronmemory.com:specs:cor:agt:110:03).

Field Argument Type Description
task AgentTask!
action PrProtocolAction!

PrincipalGrant

An individual action grant (design:grant-model): extra management actions for one member of one org, on top of their role bundle. Grantee and org are projected as scalars, never nested objects.

Field Argument Type Description
id ID!
principalType String! Grantee kind - 'USER' in v1.
principalId ID!
principalHandle String
organizationId ID!
organizationUrn String
actions [String!]! Allowed actions - exact ('memory.clone'), prefix ('memory.*'), or '*'.
expiresAt DateTime ISO-8601 expiry, or null for perpetual (until revoked).
createdAt DateTime!

PrincipalGrantsPage

Field Argument Type Description
items [PrincipalGrant!]!
total Int!

PublicInvitation

The invite-page view available to anyone holding the invitation slug.

Field Argument Type Description
memberRole Role!
maxActivations Int
activationCount Int!
expiresAt DateTime
sender PublicInvitationSender
organization PublicInvitationOrganization

PublicInvitationOrganization

Only the organization display name needed on the invite page.

Field Argument Type Description
name String!

PublicInvitationSender

Only the sender display fields needed on the invite page.

Field Argument Type Description
name String
githubUsername String

PublicOrganization

cor:acl:080:02 — a sanitized, non-member-safe view of a DISCOVERABLE org. Deliberately a SEPARATE type from Organization: it exposes only public identity + the org's public footprint, never members / private memories / apps / credentials (which the full Organization's nested resolvers would leak).

Field Argument Type Description
id ID!
name String!
urn String!
listedOnMarketplace Boolean!
publicMemories [PublicResourceRef!]! SUPERSEDED by publicMemoriesPage (#3873, hrn:node:hadronmemory.com:specs:cor:api:120:04): the org's PUBLIC, non-app-scoped memories (sanitized refs), now only the first page of 20 in (name, id) order. Use publicMemoriesPage to reach the rest.
publicAgents [PublicResourceRef!]! SUPERSEDED by publicAgentsPage (#3873, hrn:node:hadronmemory.com:specs:cor:api:120:04): the org's PUBLIC agents (sanitized refs), now only the first page of 20 in (name, id) order. Use publicAgentsPage to reach the rest.
publicMemoriesPage PublicResourceRefsPage! The org's PUBLIC, non-app-scoped memories (sanitized refs), one page in (name, id) order. limit omitted is 20, 0 is count-only, a negative limit is 0, a limit over 200 is served as 200 (never a refusal); a negative offset is 0. total counts exactly the rows the public gate admits (hrn:node:hadronmemory.com:specs:cor:acl:080:02, hrn:node:hadronmemory.com:specs:cor:api:120:04).
limit Int
offset Int
publicAgentsPage PublicResourceRefsPage! The org's PUBLIC agents (sanitized refs), one page in (name, id) order; same paging rules as publicMemoriesPage.
limit Int
offset Int

PublicResourceRef

A minimal, safe reference to a public resource (marketplace / discovery).

Field Argument Type Description
id ID!
name String!
urn String!
description String

PublicResourceRefsPage

A page of sanitized public resource refs that says whether more rows follow (#3873, hrn:node:hadronmemory.com:specs:cor:api:120:04). The marketplace catalogue keeps MarketplaceResourcePage.

Field Argument Type Description
items [PublicResourceRef!]!
total Int!
hasMore Boolean!

PullRequestReadiness

3448 — readiness ignores opaque properties (hrn:node:hadronmemory.com:specs:cor:agt:050:28).

Field Argument Type Description
ready Boolean!
head String!
slots [ReviewSlotReadiness!]!

QuotaCounter

Usage-vs-limit for one scope x action window (#510). The stored limit is the enforced value; env defaults only seed first touch.

Field Argument Type Description
id ID!
scopeKind String! app or org.
scopeId String!
action String! run.execute, llm.tokens, sms.send, or email.send.
window String! Window kind (day). The row rolls in place at UTC midnight - used resets, limit persists.
used Int!
limit Int!
resetAt DateTime!

RateLimitPolicy

Admin-only projection; no secrets, subject counters or identities.

Field Argument Type Description
fieldClass RateLimitFieldClass!
principalLimit Int!
keyLimit Int!
ipLimit Int!
windowSeconds Int!
retentionSeconds Int!
ipGroupingVersion String!
enforcementMode RateLimitEnforcementMode!
version Int!
updatedAt DateTime!

RecordAppActionResult

3449: App action and caller-readable register answer (hrn:node:hadronmemory.com:specs:cor:agt:110:03).

Field Argument Type Description
eventId ID!
action TickAction!

RecoveryEdgesPage

Field Argument Type Description
items [RecoveryGraphEdge!]!
total Int!

RecoveryEndpoint

Field Argument Type Description
id ID!
urn String!
loc String!
name String!
deletedAt DateTime

RecoveryGraphEdge

Field Argument Type Description
id ID!
name String
source RecoveryEndpoint!
target RecoveryEndpoint!

RecoveryNode

Explicit writer-only tombstone content; no generic entity relations. hrn:node:hadronmemory.com:specs:cor:dmo:010:04

Field Argument Type Description
id ID!
urn String!
memoryId ID!
loc String!
name String!
nodeType String!
description String
deletedAt DateTime!
content String

RecoveryNodeSummary

Field Argument Type Description
id ID!
urn String!
memoryId ID!
loc String!
name String!
nodeType String!
deletedAt DateTime!

RecoveryNodesPage

Field Argument Type Description
items [RecoveryNodeSummary!]!
total Int!

RegisterDefaults

Spec 049 Phase 5 — what an Agent's install-created register row is made with (plan §3.5).

Field Argument Type Description
mentionOnly Boolean!

RegisterEntriesPage

Field Argument Type Description
items [RegisterEntry!]!
total Int!

RegisterEntry

A REGISTER ENTRY (spec 049, D-2026-09-13-007): "this attendee takes part in this Channel". The attendee is a Worker when cast, otherwise an Agent in an App; both null = every attendee in the owner's context (org-wide for an organization row, App-wide for an App row). Not a trigger list — a row never starts a run. The register never grants: what the attendee may read or post is the Channel's host memory's decision. Not exportable.

Field Argument Type Description
id ID!
ownerType RegisterOwnerType!
ownerId ID! ID of the owning organization / App.
organizationId ID
appId ID
channelId ID!
channel Channel The Channel — null when you may not read its host memory (you stand on the owner side only).
attendeeWorkerId ID
attendeeAgentId ID
attendeeUrn String The attendee's URN (hrn:worker:… or the Agent's); null for 'every attendee'.
role RegisterRole!
mentionOnly Boolean! Only messages mentioning the attendee count as new for it.
installDefault Boolean! The row install materialised for the App's default Channel (D2).
description String The human's intent, free text.
createdAt DateTime!
updatedAt DateTime

RegisterRoleCandidate

Field Argument Type Description
worker AgentTaskParty!
role String
depth Int! Own Agent is zero; each base link adds one.
taskUrn String!

RegisterRoleCandidatePage

Experimental action register role-picking projection. No routing or assignment.

Field Argument Type Description
appId ID!
code String!
taskLoc String
depth Int
total Int! Total nearest-depth ties, independent of the requested page.
candidates [RegisterRoleCandidate!]!

RegisterRolePick

Field Argument Type Description
appId ID!
code String!
entries [RegisterRouteEntry!]! Worker arms carry exactly one WORKER entry; the managers arm one USER entry per manager, nearest first.

RegisterRouteEntry

Field Argument Type Description
kind RegisterRouteKind!
id ID!

RegisterViewChannel

The Channel half of a register view row; the host memory's URN only when the viewer may read it.

Field Argument Type Description
id ID!
name String!
kind ChannelKind!
loc String!
hostMemoryUrn String
hostMemoryId ID The host memory's id — like the URN, only when the viewer may read it.
lastSeq Int! The Channel's watermark — the highest seq issued, not a count.
lastMessageAt DateTime
deleted Boolean!

RegisterViewRow

One row of an attendee's RESOLVED register (spec 049 §4.3): the winning register entry for a Channel (App › organization, Worker › Agent › everyone, never unioned), the Channel's watermark, and the ATTENDEE's real standing on the host memory — canRead / canPost are the existing gates, the register grants nothing. A row the attendee cannot act on is returned with its reason, never dropped. Host memory identifiers remain gated for the VIEWER.

Field Argument Type Description
entry RegisterEntry!
namedBy RegisterNamedBy!
channel RegisterViewChannel!
lastSeenSeq Int Phase 7 — the attendee's cursor; null until read-state lands.
canRead Boolean!
canPost Boolean False for a Worker without an eligible driver (UNKNOWN_ACTOR); null only when no access subject was supplied.
disclosure RegisterDisclosure
attendeeUrn String

ReleaseWorkerPayload

1073 — what a releaseWorker call actually DID, rather than what the caller

predicted it would do.

releaseWorker used to return the post-release Worker, whose heldByUserId is null by construction — so a client could report only who held the name when it last looked. Per cor:agt:020:09 the two release paths are different ACTS: the holder's own release notifies nobody, an admin force-release must announce itself in the team chat. A receipt that cannot tell them apart describes an act that may not have happened.

Field Argument Type Description
worker Worker! The worker, re-read immediately after the guarded release and BEFORE the team-chat notice — so the interval in which another caller could bind is as narrow as it can be made. It is NOT zero, and this is a re-read rather than a snapshot of the write. So a non-null heldByUserId here is a LATER hold somebody else took, never a failed release. releasedFrom is what says the release happened; this field is current state, and the two answer different questions.
releasedFrom ReleasedFromUser The holder the WRITE ended — not the one a pre-read saw. Null when nothing was released, i.e. the name was already unheld (the idempotent path). This is the value the authorization decision was made against AND the value the guarded write matched on; #1084 made those the same user by construction, so this cannot name somebody other than whoever actually lost the name.
forced Boolean! True when the caller released SOMEBODY ELSE'S hold — the admin force-release path, the one act that takes a name without its holder acting, and the one that posts to the team chat. Computed server-side, from the authenticated principal and the hold the write ended in the same transaction. A client computing it would have to compare a value it was given against one it had to fetch, and that fetch fails on exactly the path where the answer matters. false always means the holder was YOU, or that nothing was released (releasedFrom null) — never "the server could not tell".
notified Boolean Whether the team-chat notice was posted. THREE states, deliberately: - null — no notice was owed. A self-release, or nothing released. - true — a notice was owed and posted. - false — a notice was OWED AND FAILED. The release still happened; an unreachable chat must not stop an admin recovering a departed colleague's names. A plain boolean would collapse the first and last, and a client cannot render "we may have silently failed to announce this" honestly — so the only truthful UI would be to say nothing, throwing the field away.

ReleasedFromUser

1073 — a sanitized identity for the person a release took a name FROM.

Deliberately a SEPARATE type from User, on the cor:acl:080:02 / PublicOrganization precedent: a field returning another entity's object hands the caller that entity's field resolvers, and User's default-resolved tail (policy, identityProvider, externalId, githubId, roles, maxReferrals) carries no gate of its own — it relies on the surface that returned it.

releaseWorker cannot lean on that. Its admin path exists for the departed colleague, and leaveApp DELETES the AppMember row while the hold survives — so the very case this path serves is the one where the caller has no other route to that User. Worker itself only ever exposed heldByUserId, a bare id, so a full User here would be a NEW disclosure rather than an inherited one.

Exposes what answers "who did I release", and nothing that grows back toward User. name keeps the same #384 gate it has on User rather than a second copy of the rule; the rest is public identity a URN already discloses.

Field Argument Type Description
id ID!
handle String
urn String Canonical hrn:user:<handle> URN (cor:urn:010:01). Null for a handle-less user.
name String Withheld (null) from a viewer who is not the user themselves, a platform admin, or a co-member of one of their orgs — the SAME #384 gate as User.name, reused rather than restated. An admin releasing a colleague who has left the org sees null here, and still gets id/handle/urn.

RemoveMemoryMemberPayload

Field Argument Type Description
memoryId ID!
userId ID!

ResendSender

One org-owned BYO Resend sender. The API key is encrypted and write-only.

Field Argument Type Description
id ID!
organizationId String!
from String! Fixed sender identity, e.g. Hadron Agent ; Resend enforces verification.
hasApiKey Boolean! Whether an encrypted API key is stored; the key is never returned.
enabled Boolean!
createdAt DateTime!
createdBy String
updatedAt DateTime!
updatedBy String

ResendSendersPage

Field Argument Type Description
items [ResendSender!]!
total Int!

ResolvedAiConfig

036-ai-service-config: configuration resolution result. A credential is returned only when the caller may manage its source. A resolved platform credential is decrypted only for platform ADMIN/OWNER; org ADMIN may decrypt an authorized tenant-owned config. Successor to agentAIConfig / appAIConfig.

Field Argument Type Description
configId ID!
name String!
ownerType AiConfigOwnerType! Which level matched: APP | AGENT | ORGANIZATION | HADRON_SERVER.
provider String!
model String!
apiKey String Decrypted key when authorized for the selected source; null for an identity-only result. For provider 'bedrock' a disclosed value is the JSON-encoded accessKeyId/secretAccessKey/region triple the portal stores.
params JSON
effectiveEndpoint String #1373: where requests for this config go (see AiServiceConfig.effectiveEndpoint).
effectiveApiStyle AiApiStyle #1373: the wire protocol requests use (see AiServiceConfig.effectiveApiStyle).

ResumeCandidate

1956 — one of the caller's own sessions offered by a CHOOSE answer. Never carries a claim id.

Field Argument Type Description
sessionId ID! The session to pass back as resumeSession(input: { session }) to pick this one.
workerId ID!
workerName String!
description String The session's description (its plan), when it has one.
source ResumeSource!
expiresAt DateTime When the claim lapses; null for a live session.

ResumeClaimReceipt

1956 — the receipt of a written resume claim. It names no claim id: redemption is judged by the caller's token.

Field Argument Type Description
sessionId ID!
workerId ID!
expiresAt DateTime!

ResumeSessionResult

1956 — the answer to resumeSession: the bound session, or the candidates to choose from.

Field Argument Type Description
outcome ResumeOutcome!
session Session The bound session for RESUMED and STARTED; null for CHOOSE.
candidates [ResumeCandidate!]! Empty unless outcome is CHOOSE.

ReviewQualityReport

4281 — an App's review quality measures for one UTC calendar month (hrn:node:hadronmemory.com:specs:cor:agt:130:06).

Field Argument Type Description
month String! The month asked for, YYYY-MM.
asOf DateTime! When the numbers were worked out (the database clock). A past month's numbers can still change after this.
rows [ReviewQualityRow!]! One row per family and model, a reported model apart from an unreported one, ordered by family, model, then reported first; the not-recorded row, when there is one, is last. Empty when the month has no reviews.

ReviewQualityRow

4281 — one reviewer row of the review quality measures (hrn:node:hadronmemory.com:specs:cor:agt:130:06). Every

ratio comes with its numerator and denominator: findingsPerReview = findings / reviews; shareConfirmed = confirmedFindings / findings; defectsMissedPerApprovingReview = defectsMissed / approvingReviews.

Field Argument Type Description
recorded Boolean! False for the one not-recorded row: the reviews whose verdict carries no model family or no model (a person's verdict, a worker with no open session, a session that recorded none, or a verdict from before the snapshot existed). They are never counted under a family.
family String The reviewer's model family as the verdict recorded it (a self-report); null on the not-recorded row.
model String The reviewer's model as the verdict recorded it (a self-report); null on the not-recorded row.
modelReported Boolean Whether the session had reported its model when the verdict was recorded (the verdict's modelReportedAt is set); null on the not-recorded row.
reviews Int! Finished review seats whose latest verdict falls in the month.
findings Int! All findings on those seats' tasks.
findingsPerReview Float! findings / reviews.
confirmedFindings Int! Findings whose latest disposition is fixed, accepted or deferred.
rejectedFindings Int! Findings whose latest disposition is rejected: not confirmed.
undisposedFindings Int! Findings with no disposition yet: their own count, in neither of the two above.
shareConfirmed Float confirmedFindings / findings; null when there are no findings.
approvingReviews Int! Reviews whose latest verdict is APPROVE, PASS or CARRY.
defectsMissed Int! #4287 — defects missed by the approving reviews, from the defect links (linkDefectToPullRequest, #4280): an approving review misses each defect linked to its PR whose introducedAtHead is the head it approved or an earlier one, in the order the PR's heads were first frozen, and every defect linked with no introducedAtHead. A head approved before the defect was introduced never contained it. 0 when nothing is linked.
defectsMissedPerApprovingReview Float defectsMissed / approvingReviews; null only when there is no approving review.

ReviewSlotReadiness

3448 — a required slot's current unsuperseded seat, from typed events only.

Field Argument Type Description
slot String!
currentTaskId ID
state String! The current unsuperseded seat task's AgentTask status, uppercased, or MISSING when no current seat task exists. This is task lifecycle state, not the review verdict.
verdict ReviewVerdict
head String
counts Boolean! True only when the current seat task is FINISHED, its assignment and verdict both name the frozen head, and its verdict names this slot and is APPROVE, PASS or CARRY. The verdict actor must be neither the build assignee nor a freezer of this head in the App, and no blocking negative verdict may exist at this head.

RevisionApproval

1838 — whether one revision was approved, and by which recorded approval.

Field Argument Type Description
state NodeApprovalState! NOT_APPLICABLE inside an encrypted memory; APPROVED or NOT_APPROVED otherwise (never SUPERSEDED: that is about the live text).
approved Boolean!
recordedAtRevision Int The revision the covering approval was recorded at; it can differ from this revision when only metadata changed, or the text recurs.
approvedBy String
approvedByInfo String
approvedAt DateTime

RevisionResult

Field Argument Type Description
revisionLoc String!
label String!
published Boolean!
createdAt DateTime!

ScheduleBusyInterval

Field Argument Type Description
start DateTime!
end DateTime!

ScheduleFreeBusy

Free/busy intervals for one requested schedule (calendarSchedule).

Field Argument Type Description
id ID!
busy [ScheduleBusyInterval!]!
error String Set when the provider could not resolve this schedule; the query still succeeds for the others.

Scope

A named search SCOPE: an ORDERED list of memories with exactly one owner (organization | Agent | App). Selects memories only — no saved filter, no retrieval parameters — and NEVER grants: memories is the stored list ∩ what YOU may read (D-2026-09-13-004), and hiddenMemoryCount says how many you cannot see, as a count only. Names are unique per owner; global and app are reserved (the ladder's own views). Collisions across owners in an App's context resolve App › Agent › organization, never unioned.

Field Argument Type Description
id ID!
name String!
description String
ownerType ScopeOwnerType!
ownerId ID! ID of the owning organization / Agent / App.
ownerUrn String Bare stored URN of the owner, when it has one.
memories [ScopeMemoryEntry!]! The scope's memories YOU may read, in scope order.
memoryCount Int! How many memories the scope lists in total.
hiddenMemoryCount Int! How many of them you may NOT read (count only — never their names).
createdAt DateTime!
updatedAt DateTime

ScopeExplanation

What a scope resolves to FOR YOU: which owner tier won when resolved by name, the scopes it shadowed, the readable memories in order, how many were dropped for access, and — when loc was asked — which memory would win for that address (the input the task-customization operation consumes).

Field Argument Type Description
scope Scope!
resolvedVia ScopeOwnerType!
shadowed [Scope!]! Lower-precedence scopes of the same name in that App's context (that you may read).
memories [Memory!]!
droppedCount Int!
winner Memory

ScopeMemoryEntry

Field Argument Type Description
position Int! 0-based order within the scope.
memory Memory!

ScopesPage

Field Argument Type Description
items [Scope!]!
total Int!

SearchReplaceFieldResult

Field Argument Type Description
field NodeTextField!
matches Int!

SearchReplaceNodeResult

Field Argument Type Description
nodeId ID!
loc String!
memoryId ID!
replacements Int! Total replacements across all searched fields on this node.
fields [SearchReplaceFieldResult!]!

SearchReplaceResult

Field Argument Type Description
nodesSelected Int! Unique authorized nodes selected before bulk-write protections are applied.
nodesScanned Int! Selected nodes whose requested text fields were actually inspected.
nodesSkipped Int! Selected nodes protected from inspection and replacement.
skipCounts SearchReplaceSkipCounts! Mutually exclusive skip reasons. Governance takes precedence over Channel address protection, so a node carrying both signals counts once as governed.
nodesChanged Int! Nodes with at least one replacement.
totalReplacements Int!
dryRun Boolean! Echoes the request — true means nothing was written.
results [SearchReplaceNodeResult!]! Per-node breakdown; only nodes with at least one match are listed.
plan String Opaque exact preview fingerprint on the spec door; null on the generic door.
skips [SearchReplaceSkip!] Node-addressed protected selections on the spec door; null on the generic door.

SearchReplaceSkip

Field Argument Type Description
nodeId ID!
loc String!
memoryId ID!
reason SearchReplaceSkipReason!
governedKinds [String!]!

SearchReplaceSkipCounts

Mutually exclusive reasons selected nodes were protected from bulk replacement.

Field Argument Type Description
governed Int! Governed nodes of any kind. This is not a spec-only count.
protectedAddress Int! Nodes at or below a Channel address.

SearchScopeInfo

Spec 049 — the scope a search ran under (every result discloses it, D-2026-09-13-002). kind: scope | app | global | user-owned. source: call | session | active-app | active-org | trigger (a headless run snapshot). memoryUrns lists only the memories YOU may read; droppedCount is how many the scope lists that you may not — a count, never their names.

Field Argument Type Description
kind String!
source String!
label String!
ownerUrn String
memoryUrns [String!]!
droppedCount Int!

Secret

One named, owner-scoped secret — the general secret store (#677). Polymorphic owner (user | org | app). The value is encrypted at rest and WRITE-ONLY: no field here ever returns it — kind + metadata are the inspectable half (you can see THAT a secret exists and, for webfetch-auth, WHERE it applies, without decrypting). A bare name resolves at run time via the CSS cascade, most-specific-first: user -> org. An App-owned secret is NEVER in that cascade: no run resolves it (hrn:node:hadronmemory.com:specs:cor:sec:020:01). An App secret keeps its values as versions: every store adds one (hrn:node:hadronmemory.com:specs:cor:sec:010:03).

Field Argument Type Description
id ID!
ownerType String! Owner scope: user | org | app.
ownerId ID!
name String! Cascade-resolution key; unique per owner; lowercase [a-z0-9-], max 64.
kind String! Extensible kind; v1: generic | webfetch-auth.
metadata JSON The NON-secret, inspectable half (webfetch-auth: { type, urlPrefix }).
createdAt DateTime!
createdBy String
updatedAt DateTime!
updatedBy String
protected Boolean! Whether changes need a person's change request. App secrets only; always false for org and user secrets.
currentVersion Int The newest version's number. App secrets only; null for org and user secrets (they have no versions).
versions SecretVersionsPage! An App secret's kept versions, newest first: numbers, sizes and authorship, never a value. Paged (hrn:node:hadronmemory.com:specs:cor:api:120:04): default 20, cap 200, limit 0 counts only. Empty for org and user secrets.
limit Int
offset Int

SecretEvent

One audit event of an App secret: who did what, when, with what outcome. Never a value.

Field Argument Type Description
id ID!
ownerType String!
ownerId ID!
secretId ID!
secretName String!
versionNo Int
kind String! STORE | VERSION | METADATA | DELETE.
outcome String!
actorUserId String
workerId String
sessionId String
at DateTime!

SecretEventsPage

Field Argument Type Description
items [SecretEvent!]!
total Int!

SecretVersion

One stored value of an App-owned secret, as metadata only: there is no field that returns the value or its ciphertext.

Field Argument Type Description
id ID!
versionNo Int!
sizeBytes Int! Bytes of the stored value.
writtenAt DateTime!
writtenByUserId String
writtenByWorkerId String
supersededAt DateTime Set when a newer version was stored; null on the current version.

SecretVersionsPage

Field Argument Type Description
items [SecretVersion!]!
total Int!
hasMore Boolean! Whether versions remain past this page.

SecretsPage

Uniform paginated list shape (cor:api:120).

Field Argument Type Description
items [Secret!]!
total Int!

ServedPrompt

2047 / hrn:node:hadronmemory.com:specs:cor:agt:040:03: what a bind, a chatbot chat or a headless run was given. Immutable platform data, never

editable and never exported. Names the compiled revision served by (compiledNodeId, servedRevSeq), the pointer level that chose it, that revision's own provenance and the values the platform variables were filled with. No composed text.

Field Argument Type Description
currentLint LintWarningPage Current warnings for this record's provenanceRevSeq, never the newest compile.
first Int
after String
id ID!
kind ServedPromptKind!
pointerLevel ServedPromptPointerLevel!
compiledNodeId ID!
servedRevSeq Int! Node.revSeq of the revision served (never contentRevSeq).
provenanceRevSeq Int! The compile revision that owns the provenance.
compiledContentHash String!
ordinal Int! 1 for a bind or a run; a chat counts up each time its served revision or filled variable values change (#3096).
variables JSON! Recorded platform values. Chat records label session.llmModel.source as client-reported or unspecified (#3096); neither is verified model identity.
servedAt DateTime!
pruned Boolean! True when the served revision is no longer retained (neither current nor in history).
provenance ServedPromptProvenancePage! Provenance of the served revision, one page at a time (default 50, cap 200).
limit Int
offset Int

ServedPromptProvenanceEntry

2047 / hrn:node:hadronmemory.com:specs:cor:agt:040:03: one entry of a served revision's provenance. Ids, revisions and hashes only: never a loc, a

title, a node or text, so reading provenance hands the caller no included part. pruned is true when that revision is no longer retained.

Field Argument Type Description
nodeId ID!
revSeq Int!
hash String!
pruned Boolean!

ServedPromptProvenancePage

Field Argument Type Description
items [ServedPromptProvenanceEntry!]!
total Int!

ServedPromptsPage

Field Argument Type Description
items [ServedPrompt!]!
total Int!

ServerInfo

Identity of the running hadron-server (see Query.serverInfo).

Field Argument Type Description
signing Boolean! Present and true only when this deployment offers node signing. Discovery never grants access to sign.
passkeyRegistration Boolean! Present and true only when passkey registration is enabled separately from node signing.
passkeyRevokeUrl String! #4051: the fixed, parameterless URL of the passkey revoke page (the deployment's baseUrl in this same response plus /passkeys/revoke), for a client that hands the owner off to it (hrn:node:hadronmemory.com:specs:cor:aut:040:08). Present only while passkey registration is enabled, exactly like passkeyRegistration: while it is off the field is removed from the schema, never null (hrn:node:hadronmemory.com:specs:cor:api:020:01), so check the passkey-registration token on GET /capabilities before selecting it. It names no passkey, credential, user or session, and is the same for every caller. Revoking happens interactively on that page; the URL grants nothing.
version String! HADRON_SERVER_VERSION — the MCP/API-surface contract version.
baseUrl String! The deployment's canonical base URL (BASE_URL, else the local default).

Session

A unit of work recorded against a user or App: the general row, and what the bare word "session" means throughout this schema (#1034). type says which kind — DEVELOPER, CHATBOT, AUTOMATION, EDGE — and workerId is optional.

A worker session is the subtype with workerId set: a Worker (named casting) bound to a driver, which is what makes work attributable to a teammate and what a merged PR traces back through. Binding is optional, so a list of these is not a staff view and may hold no worker sessions at all — read workerId per row rather than assuming either way.

A chat session is NOT one of these and has no row here: it is the conversation a human is in — the Claude Desktop window, the Claude Code session, the IDE chat. The two are independent and ending one does not end the other: a chat session that closes leaves its worker session open until endSession. Since #1114 nothing ends it for inactivity — silence is not evidence of abandonment — but it stops reading as LIVE once nobody has driven it inside its idle window, so the stale session stops blocking another bind without being ended or losing its unwritten handoff. That changes no HOLD: a human-held name stays held until explicit release, so only its holder can bind it again. Do not use "chat session" for a Chat (the agent conversation entity) — that is an agent chat, a third concept.

Field Argument Type Description
id ID!
type String! Which kind of session this is: DEVELOPER, CHATBOT, AUTOMATION or EDGE.
appId String
userId String
agentId String The role-agent driving the session (with workerId set, the agent behind the casting).
role String #2458 (hrn:node:hadronmemory.com:specs:cor:dmo:050:11): the worker's role when this session was bound; it does not follow a later change of the worker's agent. Null without a worker.
workerId String #974 / cor:agt:020:03: the Worker (named casting) this session works as.
worker Worker #980 / cor:agt:020:02: the Worker behind workerId, nested — so a session list can render the app-qualified compound ('eng-team/Iris') without a per-row worker(ref:) + app(ref:) round trip (Worker carries name and app). Resolves for RETIRED workers too: retirement ends the casting, not the history, so past sessions stay attributable. Worker.app and Worker.agent run their OWN read gates and mask to null on deny (#552), so this nesting never widens what the session read admits.
memoryId String
expiresAt DateTime
repo String
branch String
prNumber Int
customerId String
language String
plan String
llmModel String
transcriptPath String #928: where the driving tool's transcript lives on 'host'.
host String #928: machine identifier the session ran on.
tool String #928: the tool driving the session ('claude-code', 'codex', ...).
family String #1707 — the model family this session runs as (hrn:node:hadronmemory.com:specs:cor:agt:060:04): given at start, or derived from llmModel then tool; null when it could not be classified. A bound worker's family is its newest open session's. A matching input only, never an authorization input: it is self-declared.
effort EffortLevel #4291 — the effort this session runs at (hrn:node:hadronmemory.com:specs:cor:agt:060:04), as the launcher applied it and the session reported it at start, on a resume or through updateSession. Null until reported; NOT_APPLICABLE for a family with no effort control. A report, never a control: nothing makes a running session adopt a value.
launchHostId String #1709 — a host-launched session (hrn:node:hadronmemory.com:specs:cor:agt:070:08): the host that started it. Null for a session started by hand.
launchOperationId ID #1709 — the worker.start operation that launched it.
launchTaskId ID #1709 — the task it was launched for; null for a manager's start without one.
launchIssuedBy String #1709 — who issued the start: platform (an assignment) or manager.
inputTokens Int
outputTokens Int
turnCount Int
errorCount Int
parentSessionId String
prevSessionId String
summary String
outcome Float
outcomeRef String
outcomeMeta JSON
startedAt DateTime!
endedAt DateTime
endReason SessionEndReason #1156 — hrn:node:hadronmemory.com:specs:cor:dmo:070:05: null while open; stamped cause after end, unknown for legacy ends. Readable wherever this Session is; no ending actor.
supersededBySessionId String #3818 V25 — hrn:node:hadronmemory.com:specs:cor:dmo:070:05: immediate superseding session id; null unless that successor is currently readable under hrn:node:hadronmemory.com:specs:cor:agt:020:03. No historical backfill.
autoExpiredAt DateTime
isLive Boolean! hadron-cli#791 / hrn:node:hadronmemory.com:specs:cor:agt:020:11: whether THIS session is live: not ended or hard-expired (hrn:node:hadronmemory.com:specs:cor:agt:020:03), AND driven inside its type's idle window (activity is the latest of startedAt, the heartbeat updatedAt, and the latest attributed usage event, capped at endedAt). The same derived predicate as startSession's WORKER_TAKEN gate and Worker.hasLiveSession, so the three always agree. An unexpired open session that is not live has LAPSED: nobody drove it inside the window, so another driver may bind its worker; it is not ended, and can still be ended with a handoff. False for an ended or deleted session.
state SessionState! #2288 / hrn:node:hadronmemory.com:specs:cor:agt:020:13: this session's derived state, using its own App's dormancy period (platform default when App-less), never the viewer's App. ENDED means terminal: an explicit/reaped end, deletion, or now >= promised expiresAt before reap. It does not assert an explicit ending act. Otherwise DORMANT uses the same activity and strict older-than threshold as the resume refusal. At exact dormancy equality it is not dormant. LIVE includes idle deadline equality; hard expiry is exclusive even when the deadlines coincide. The remaining open sessions are LAPSED. Reading state never drives or resumes a session.
lapsesAt DateTime #1617 / #1036: the earlier of last activity plus the type's idle window and a promised expiresAt (hrn:node:hadronmemory.com:specs:cor:agt:020:03). The idle deadline is inclusive; a hard expiry is exclusive: the session is expired at now >= expiresAt, even before the reaper runs. Driving it can renew its idle deadline, never its promised expiry. Null for an ended or deleted session.
events [UsageEvent!]! The session's latest 50 usage events that touched no memory or a memory the caller can read (hrn:node:hadronmemory.com:specs:cor:acl:090:01, ruling 0249). In the caller's own session every event is whole. In any other session, an event the caller did not record (another user's, or the App's) shows volume only: userId, organizationId and actionArgs are null, appId is kept only when it is the calling App's own, and sessionId is this session's id. Admins get the same, and an impersonated read is not the target's own session.
servedPrompts ServedPromptsPage! #2047 / hrn:node:hadronmemory.com:specs:cor:agt:040:03: the boot prompt this session was served at its bind. Readable by whoever may read the worker's internals; an empty page for anyone else.
limit Int
offset Int

SessionPage

2212 — one page of sessions in the caller's session scope.

Field Argument Type Description
items [Session!]!
total Int!
hasMore Boolean!

SetHostWorkerTerminalsResult

2924 — status reporting only: no alarm verdict or coordinator requirement.

Field Argument Type Description
stored [WorkerTerminalRef!]!
refused [WorkerTerminalRefusal!]!

SharedOrganization

Only safe identity scalars for a live organization shared with the effective human viewer.

Field Argument Type Description
id ID!
name String!
urn String!

SharedOrganizationsPage

Field Argument Type Description
items [SharedOrganization!]!
total Int!

SigningRequest

1632 (hrn:node:hadronmemory.com:specs:cor:dmo:130:03) — a request for a person to sign one node's content, pinned at creation.

Field Argument Type Description
id ID! 128 bits of randomness.
nodeId ID!
nodeUrn String
revision Int! The revision pinned at creation.
approvalHash String! The approval hash v1 of the pinned content (64 lowercase hex).
payloadVersion String! The signature payload version the signer signs: hadron-signature-v3 (hrn:node:hadronmemory.com:specs:cor:dmo:130:01). A request still open with a v1 pin when v3 deployed ended STALE.
state SigningRequestState! The effective state.
namedSigner NodeRevisionEditor Null: any writer of the node's memory may sign.
requestedBy SigningRequester!
createdAt DateTime!
expiresAt DateTime!
endedAt DateTime Null while OPEN. EXPIRED ends at expiresAt; every other end at the moment it happened (DB clock).
signature NodeSignature The signature that completed it; null unless COMPLETED (and when the record does not verify).
ceremonyUrl String! The server-hosted ceremony page where the signer signs (hrn:node:hadronmemory.com:specs:cor:dmo:130:08): the server origin plus /signing/<id>, with no token. Copy it verbatim; never compose it. A person signs there with a passkey; no GraphQL or MCP call takes an assertion. An ended request's link only explains that it ended.

SigningRequester

1632 — who asked for a signature. The requester account is userId, else appId (#10397).

Field Argument Type Description
userId ID
appId ID Set only when an App key itself asked.
workerId ID The Worker whose session made the request, when one did.
sessionId ID

SigningRequestsPage

One page of a node's signing requests, including ended requests. hrn:node:hadronmemory.com:specs:cor:api:120:04.

Field Argument Type Description
items [SigningRequest!]!
total Int!
hasMore Boolean!
nextCursor String

SkillExportPlanEntry

The server's filesystem plan for one skill. The client still performs and reports actual local I/O; this object records only what the server judged safe.

Field Argument Type Description
action SkillExportAction!
preservesExistingFile Boolean! True when the client must leave any installed file unchanged.
reasons [SkillExportReason!]!

SkillExportReason

One server-owned reason for an export action.

Field Argument Type Description
code String! Stable machine-readable reason, usually a drift class or lint rule.
message String! Actionable text clients can display without recreating server policy.

SkillFinding

One lint result, carrying the node and memory so a renderer never looks them back up.

Field Argument Type Description
urn String!
memory String!
rule String!
severity String! Either error or warning — the same vocabulary spec lint renders.
message String!

SkillOrphan

A file that paired with no declared node. Never removed without an explicit prune.

Field Argument Type Description
dirName String!
sourceUrn String
nodeId String

SkillPlan

Field Argument Type Description
entries [SkillPlanEntry!]!
orphans [SkillOrphan!]!
orphanAssessmentSkipped Boolean! True for scoped or selected exports: out-of-selection files are not classified as orphans.
scopeSelection SkillPlanScopeSelection Non-null only when EXPORT selected a persisted Scope.
selectionResults [SkillSelectionResult!]! Opaque unavailable refs and selected nodes with no declaration for this host.
scanned Int! How many nodes carrying ANY declaration key were in scope. A plan over an empty corpus and a plan the caller cannot see are otherwise the same empty list, and a client that cannot tell them apart reports nothing-to-do for a corpus it was denied.
judged Int! How many of those were judged for THIS host — the number of entries. A node declaring only another host is scanned and not judged, so the two differ by design; the gap is a fact about the corpus, not a discrepancy.
unrecognized [SkillPlanUnrecognized!]! Nodes in scope carrying a key under properties.exports that names no host (#1292, cor:agt:030:06): an unrecognised key is reported, never read as an alias, and never blocks anything. HOST-INDEPENDENT: the list is identical in every host's plan, because the key belongs to none of them, so a client reports each node once rather than once per host. A node here may also have an entry, when it declares a known host too; one declaring only unknown keys has none, and is part of the scanned-minus-judged gap.

SkillPlanEntry

Field Argument Type Description
urn String!
nodeId String!
revision Int! Authoritative current node revision used in rendered provenance.
name String! The stored skill name (D12 retired derivation).
class String One of: current, stale, locally-edited, renamed, never-exported, orphaned, unhashed, collision, unavailable, disabled. Null when the file could not be parsed — a parse failure is reported as a FAILURE, not as a class.
parseFailure Boolean! True when the file exists and does not parse. Reported identically by status and export.
movedFrom String Source directory selected for a MOVE or REMOVE action; also reported for the renamed class.
findings [SkillFinding!]!
renderedBody String Present only for EXPORT, only for a class whose action writes, and only when the node has no error findings — so a client cannot write a file the server already judged broken.
exportPlan SkillExportPlanEntry Present only for EXPORT. This is a planned action and its server-owned reasons, not evidence that the client completed a filesystem write.
outOfExportReason String Why an enabled source is out of export in STATUS or EXPORT, or null when this category does not apply. Separate from the planned filesystem action.

SkillPlanScopeSelection

The live, access-intersected Scope selection used by this EXPORT plan.

Field Argument Type Description
id ID!
name String!
readableMemoryCount Int!
droppedCount Int!
fingerprint String! Stable digest for comparing separate host plans from one export.

SkillPlanUnrecognized

A node carrying one or more exports keys that name no host (#1292).

Field Argument Type Description
urn String!
nodeId String!
name String! The node's display name, not a skill name: an unrecognised key has no host, so it declares no skill name anyone reads.
memory String!
keyCount Int! How many unrecognised keys the node carries — the true total, whether or not each is listed.
keys [String!]! The unrecognised keys LISTED, in UTF-8 byte order — e.g. codex for properties.exports.codex. At most 10, and none over 128 bytes: the report is bounded because properties is writer-controlled. keyCount is the total; anything not listed is counted in one extra warning, never dropped silently.
findings [SkillFinding!]! One warning per listed key, plus one for any not listed. Attributed to no host; never blocks.

SkillSelectionResult

A named task that cannot produce a host entry. An unavailable ref reveals no node metadata.

Field Argument Type Description
ref String!
nodeId String
action SkillExportAction!
reason SkillExportReason!

SlackConnection

One Slack workspace install of the Hadron Slack app (spec 043). Org-owned, workspace granularity: defaultAppId names the Hadron App that serves /hadron commands from this workspace. The bot + app tokens live ENCRYPTED IN THE TOOL (hadrontool-slack) — they are write-only inputs on createSlackConnection and no field here ever returns them.

Field Argument Type Description
id ID!
organizationId String!
defaultAppId String!
provider String! Slack provider backing this connection ('slack' today).
teamId String! Slack workspace (team) id, e.g. T0123456789.
teamName String!
botUserId String! The bot's Slack USER id (U…) — the sender on messages it posts.
botId String! The bot's BOT id (B…) — what bot message events carry. Distinct from botUserId; the bridge loop filter needs both.
status String! 'ACTIVE' or 'ERROR' (the tool's connection-status vocabulary).
lastError String
createdAt DateTime!
updatedAt DateTime!

SlackConnectionsPage

Uniform paginated list shape (cor:api:120).

Field Argument Type Description
items [SlackConnection!]!
total Int!

SpecCorpusMintReport

1448 — the mint report. blockers must all be gone for a mint to succeed.

staleAbstracts are listed separately, over every node in this mint's scope (a minted, unchanged node is not counted; spec validate audits the whole memory); they block only when staleAbstractsBlock is true. openQuestions never block.

Field Argument Type Description
memoryId ID!
dryRun Boolean!
minted Boolean! True when this call stamped nodes in its mint scope; false for a dry run or an empty scope.
blockers [SpecMintFinding!]!
staleAbstracts [SpecMintFinding!]!
staleAbstractsBlock Boolean!
openQuestions [SpecOpenQuestionGroup!]!
mintedCount Int! #1591 — how many nodes this call minted (0 on a dry run or refusal).
mintLocs [String!]! #1591 — the locs of NEW nodes this call minted, or would mint on a dry run, ordered by loc.
remintLocs [String!]! #1612 — the locs of already-minted nodes this call re-minted (edited since, or minted with no recorded revision), or would on a dry run, ordered by loc. A re-mint keeps the first mint's time and minter.
remintedCount Int! #1612 — how many of mintedCount were re-mints.
unresolvedFeedback [UnresolvedFeedback!]! #1607 — nodes in mintLocs with open discussion: a WARNING, never a blocker (hrn:node:hadronmemory.com:specs:cor:dmo:110:07). Ordered by loc.

SpecDocument

1302 — a Feature's specs as one document (see Query.specDocument).

Field Argument Type Description
memoryId ID!
loc String! The citation the document was built for.
renderedAt DateTime! The time in the text's header.
markdown String! The whole document, one Markdown string (hrn:node:hadronmemory.com:specs:cor:spc:030:02). Every client shows this string unchanged.
entries [SpecDocumentEntry!]! One entry per spec the document covers, in document order, the Feature first.

SpecDocumentEntry

1302 — one spec in a document, read as the caller would read the node.

Field Argument Type Description
loc String!
urn String!
name String!
revision Int!
content String The body as an ordinary read returns it (includes resolved under the caller's own access). Null for a placeholder.
isPlaceholder Boolean!
approvalStatus NodeApprovalStatus!
mintStatus NodeMintStatus!

SpecMintFinding

1448 — one item in a mint report. loc is where it was found; targetLoc the cited spec, for a reference.

Field Argument Type Description
kind SpecMintFindingKind!
loc String!
rule String
message String!
targetLoc String

SpecOpenQuestion

1448 — one open question in the corpus (report-only, never blocks minting).

Field Argument Type Description
loc String!
question String!

SpecOpenQuestionGroup

1448 — open questions grouped by who decides; decider null means unassigned.

Field Argument Type Description
decider String
questions [SpecOpenQuestion!]!

SpecReference

1449 — one reference to a spec in a draft corpus. For kind URN, field is

the text field it was found in and text the URN as written; for kind EDGE, field is 'edge' and text the edge's relationship name.

Field Argument Type Description
kind SpecReferenceKind!
sourceNodeId ID!
sourceLoc String!
field String! The scanned field; edge for a real edge; pendingEdge for an edge whose target is not a node yet.
targetLoc String! The cited loc; for an edge into another memory, the target's node URN; for a pendingEdge not yet resolved to a node, its target as recorded (a loc, file id or URN).
text String
reason SpecReferenceProblem Set only by specUnresolvedReferences and specUnresolvedReferencesPage.

SpecReferencePage

3222 (#2213 S3) — one page of a spec-reference list, counted over the whole list.

Field Argument Type Description
items [SpecReference!]!
total Int!
hasMore Boolean!

SpecRenumberMove

1449 — one spec a renumber moves (the spec or a descendant).

Field Argument Type Description
fromLoc String!
toLoc String!

SpecRenumberResult

1449 — the result (or, with dryRun, the plan) of renumberSpec.

Field Argument Type Description
dryRun Boolean!
moved [SpecRenumberMove!]!
rewrites [SpecRenumberRewrite!]!
textCitations [SpecTextCitation!]!

SpecRenumberRewrite

1449 — one node whose URN references a renumber rewrites.

Field Argument Type Description
nodeId ID!
loc String!
fields [String!]! The text fields rewritten.
count Int! How many URN references were rewritten.
status SpecRewriteStatus!
error String

SpecTextCitation

1449 — a moved citation that appears as bare TEXT (a link label, a node

name, prose). Reported, never rewritten: it cannot be told apart from other characters in prose.

Field Argument Type Description
sourceNodeId ID!
sourceLoc String!
field String!
citation String!
excerpt String! A short window of text around the citation.

StartImpersonationResult

Returned exactly once by startImpersonation — the token is never stored or shown again (UserApiKey rawKey precedent).

Field Argument Type Description
session ImpersonationSession!
token String!

StopSignal

2022 (hrn:node:hadronmemory.com:specs:cor:agt:090:01) — a stop signal. Ids and times only; it never changes once set, except that its end is recorded.

Field Argument Type Description
id ID!
level StopSignalLevel!
scope StopSignalScope!
targetWorkerId ID WORKER and TEAM: the target worker (a team by its head).
targetHostId String HOST: the target host's id.
setAt DateTime!
until DateTime When it ends on its own, if set to.
setByUserId ID The person who set it; null when a host key did.
setByHostKey Boolean!
live Boolean! Not ended and its until, when given, still ahead.
endedAt DateTime When it was lifted, or its until (an expiry is in effect at its until).
endKind StopSignalEndKind
endedByUserId ID
endedByHostKey Boolean!

StopSignalPage

Field Argument Type Description
signals [StopSignal!]!
pageInfo DueWakePageInfo!

SubscribeResult

Field Argument Type Description
subscription TickerSubscription!
announcement GrantAnnouncement Set only when the call used the grant: whether the team-chat post went out.

SummarizationRequest

Retained for ChatPromptResult.summarizationNeeded, which is currently always null (#1115). Kept so the schema does not break clients that still select the field.

Field Argument Type Description
messageCount Int!
prompt String!

TeamAttentionChannel

1353 — compact unread metadata for one Worker/Channel pair. No message body is returned.

Field Argument Type Description
channel ID!
name String!
unread Int!
unreadMentions Int!
firstUnreadSeq Int
lastSeq Int!

TeamAttentionPage

Field Argument Type Description
items [TeamAttentionPageItem!]!
scanComplete Boolean! False while any Channel is unfinished or queued items remain undelivered.
nextPage String Continuation for the next pull; null on the final page.
adoptableSince String FINAL PAGE ONLY: a since-watermark token (same shape v1 issued) to adopt after every listed nudge was accepted. Never present while scanComplete is false.

TeamAttentionPageItem

1384 paged (v2): one bounded slice of an attention scan. Counts are exact

for the captured (seen, head] range of the issuing scan only, and items are emitted solely from Channels that scan has exhausted.

Field Argument Type Description
worker ID!
workerName String!
workerUrn String
channel ID!
channelName String!
unread Int!
unreadMentions Int!
firstUnreadSeq Int
lastRelevantSeq Int
lastSeq Int! The frozen Channel head this item's counts are exact for.

TeamAttentionPreviewPage

Field Argument Type Description
items [TeamAttentionPageItem!]!
scanComplete Boolean!
nextPage String
proof String FINAL PAGE ONLY: the short-lived switchover proof (frozen heads). An incomplete preview never carries one, so a partial preview can never silently discard an unscanned backlog.
expiresAt DateTime

TeamAttentionResult

Field Argument Type Description
token String! Opaque signed snapshot. Adopt it only after every listed nudge is accepted.
workers [TeamAttentionWorker!]!

TeamAttentionSwitchoverChannel

Field Argument Type Description
channel ID!
name String!
fromSeq Int!
throughSeq Int!
unread Int!
unreadMentions Int!

TeamAttentionSwitchoverPreview

Field Argument Type Description
proof String! Short-lived proof binding the exact operator, App, Workers, registers, cursors and heads shown here.
expiresAt DateTime!
workers [TeamAttentionSwitchoverWorker!]!

TeamAttentionSwitchoverResult

Field Argument Type Description
applied Boolean!
workersAdvanced Int!
channelsAdvanced Int!

TeamAttentionSwitchoverWorker

Field Argument Type Description
worker ID!
name String!
urn String
channels [TeamAttentionSwitchoverChannel!]!

TeamAttentionWorker

1353 — one live Worker that has relevant unread attention after the supplied token.

Field Argument Type Description
worker ID!
name String!
urn String
live Boolean!
channels [TeamAttentionChannel!]!

TeamAvailability

1706 — every availability record in one App.

Field Argument Type Description
workers [WorkerAvailability!]!
families [ModelFamilyAvailability!]!

TeamChatMessage

One message in a team App's chat (#939, Worker envelope since #974). Exactly one of authorUserId / authorWorkerId is set, or authorSystem is true (#1791, the platform's own notice, which has neither): a human post carries the user, a worker post carries the Worker (the named casting, cor:dmo:050:11) plus the driving sessionId. mentions holds the lowercased tokens extracted server-side at write time (the '@worker-name / @handle' format, stored without the '@').

Field Argument Type Description
nodeId ID! The message node's id.
urn String The message node's canonical URN, hrn:node:<memory>:<loc> (#1209), so a client can cite a message in a CLI call, an MCP tool or a reply. Composed server-side: a message loc carries a random component, so the chat root and the seq do not reconstruct it. Null when the address would not resolve back to this message: the host memory's stored URN or the loc cannot be emitted in the flat grammar-v2 shape, or the memory URN is a pre-v2 compound one (e.g. a legacy team space). A client shows nothing then, never a guessed address (the Worker.urn / Channel.urn contract).
seq Int! Ordering key, unique per chat, allocated atomically (ascending from 1).
body String!
at DateTime!
authorUserId ID
authorWorkerId ID
authorSystem Boolean! #1791 — posted by the platform itself (a system author, neither a user nor a worker): the wake-budget notice. Carries no mentions.
authorName String Display convenience: the worker name or the user handle.
authorAppId ID Spec 049 Phase 8 (item J): the Worker's App when the post crossed Apps — visible as one in the transcript.
sessionId ID The session driving the worker author, when posted via sessionRef.
replyToSeq Int The seq this message replies to, when it is a reply.
mentions [String!]!
teamTags [TeamTagSnapshot!] Immutable head identity/display pairs. Null means absent or withheld; [] means known empty.

TeamChatMessagesPage

Field Argument Type Description
items [TeamChatMessage!]!
total Int! Number of canonical messages matching this read's sinceSeq/beforeSeq cursor range and mentionsRef filter, before limit/offset. It is not the total number of messages in the chat or Channel when a cursor/filter is present.
channelId ID #2181 — the Channel this page was read from. NULL only when the App has no team channel yet.
channelIncarnation Int #2181 — that Channel's incarnation at the read; pin the next read or mark with expectedIncarnation.

TeamChatSearchMatch

One match of a chat-history search (#2299, hrn:node:hadronmemory.com:specs:cor:agt:020:04): the canonical message reference a read returns, and nothing else. No body, no snippet: the caller reads the message to see it.

Field Argument Type Description
nodeId ID! The message node's id.
urn String The message's canonical URN, as TeamChatMessage.urn (null when it would not resolve back to the message).
seq Int!
channelId ID! The Channel searched.
channelIncarnation Int! That Channel's incarnation at the search.

TeamChatSearchPage

One page of a chat-history search (#2299, hrn:node:hadronmemory.com:specs:cor:agt:020:04). Newest first. A call stops at a full page or at the scan bound, whichever comes first: complete is true only when the search reached the start of the history, and then there is no cursor. A search found nothing only when every page it returned was empty and the last one has complete true. A final empty page with complete true can follow pages that had matches. An empty page with complete false means the scan bound fired; continue with the cursor.

Field Argument Type Description
items [TeamChatSearchMatch!]!
complete Boolean! True when the search reached the start of the history (no cursor), false when it stopped at a full page or the scan bound.
cursor String Opaque continuation, bound to the query, the Channel, its incarnation and the caller; any other use is TEAM_CHAT_SEARCH_CURSOR_INVALID. After a full page it resumes after the last match; after the scan bound it resumes below the last scanned message, so nothing is scanned twice or skipped. Null when complete.
channelId ID The Channel searched. NULL only when the App has no team chat yet (then complete is true and the page empty).
channelIncarnation Int

TeamCollectionsPayload

Result of updateTeamCollections (hadron-cli#401).

Field Argument Type Description
memoryId ID! The team App's shared memory the declaration was written to.
collections [String!]! The server-owned collections declared on it.
changed Boolean! False when the declaration already matched the canonical definition (idempotent no-op).

TeamComposition

2061 — active roster workers grouped by their direct reportsTo claim.

Field Argument Type Description
appId ID!
asOf DateTime!
lanes [TeamCompositionLane!]! Lanes ordered by coordinator name (case-insensitive), then URN; the unassigned lane is last. Empty teams have no lanes.

TeamCompositionLane

A direct-report group, not a hierarchy rollup. A coordinator's own row belongs only in its own reportsTo lane.

Field Argument Type Description
coordinator AgentTaskParty Sanitized coordinator identity, including retired coordinators; null for the single unassigned lane.
coordinatorRetired Boolean!
workers [TeamCompositionWorker!]! Non-retired workers only, retaining roster name order. No role, including saas-pm, is excluded.
countsByRole [TeamRoleCount!]! Plain headcounts, role ascending with null last; null is its own bucket.
countsByRoleFamily [TeamRoleFamilyCount!]! Plain headcounts by role then family, null last in each dimension; nulls are retained as their own buckets.

TeamCompositionWorker

A closed roster projection; no task, holder or raw Worker fields.

Field Argument Type Description
worker AgentTaskParty!
role String
family String
bound Boolean!
liveSession Boolean!
state TeamRosterState!

TeamPause

2138: the App's team pause. teamPausedAt is null when the team is not paused.

Field Argument Type Description
teamPausedAt DateTime

TeamRole

A role definition (#960): the roles:<role> node in the Team Agent's system memory. #1050: it carries no name register — a role is a definition, not an allocation pool. The boot prompt is NOT here — it is the role-agent's compiled boot prompt (hrn:node:hadronmemory.com:specs:cor:agt:040:07); roleAgent points at it.

Field Argument Type Description
role String! The role slug, e.g. backend-engineer.
loc String! The node loc: roles:<role>.
nodeId ID!
description String
repos [String!]! #1024 — the repos a worker in this role normally works in, from `data.repos`. A SOFT signal for clients to warn on a role/repo mismatch at session start (hadron-cli#456): a worker bound as a server-engineer with `--repo …/hadron-cli` is usually a mistake and is sometimes deliberate. NEVER a refusal, and never inferred. Cross-repo work is legitimate — a coordinator does it by definition, and sibling repos share code — so a hard gate would be wrong the first time someone makes a genuine cross-cutting change. Affinity is declared, not guessed from the role slug, which happens to work for `cli-engineer` → `hadron-cli` and breaks for any team whose repo names do not match their role names. EMPTY AND UNSET ARE THE SAME: no affinity, never warn. A client cannot usefully act differently on the two, since "spans everything" and "not configured yet" both mean do-not-warn, and distinguishing them would make an unconfigured team look misconfigured.
roleAgent Agent The single installed agent whose personaRole matches this role — exactly the agent a role-mode castWorker would use (null when zero or ambiguous). Runs Query.agent's own read gate and masks to null on deny (the #552 posture), like Worker.agent.
hasNamePlaceholder ⚠️ Boolean Always null. The name-placeholder check was retired with the old variable logic (#2049).

⚠️ DEPRECATED

Retired (#2049); always null.

TeamRoleCount

Field Argument Type Description
role String
count Int!

TeamRoleFamilyCount

Field Argument Type Description
role String
family String
count Int!

TeamRolesPage

Field Argument Type Description
items [TeamRole!]!
total Int!

TeamRoster

1707 — the team roster of one App.

Field Argument Type Description
appId ID!
asOf DateTime!
workers [TeamRosterEntry!]!

TeamRosterEntry

1707 — one worker on the team roster.

Field Argument Type Description
worker AgentTaskParty!
role String
state TeamRosterState!
bound Boolean! Bound: has an open session, live or quiet. Going quiet never unbinds; ending the session does.
liveSession Boolean! Has a live session (hrn:node:hadronmemory.com:specs:cor:agt:020:11). Matching does not need one: a BOUND worker with an open session (quiet or live) that has reported a family is matched, and a host start is issued only for a worker with no open session; an unbound worker is matched when a live host can launch it.
family String The binding's model family: its newest open session's (hrn:node:hadronmemory.com:specs:cor:agt:060:04), kept while the session is quiet. Null when unbound or none was reported.
model String Self-reported model of the same newest open binding as family, retained while quiet. Null when unbound or unreported; advisory, never authorization.
modelReportedAt DateTime When that binding last reported its model; null when unbound or never reported. Not inferred from session activity.
modelGroups [String!] Current matching model-group names, resolved live from the Team Agent and App overrides. Empty without a reported model or match; null with a field error if group lookup fails. Uses this roster's existing audience; group configuration is read live when selected. Advisory only, never authorization (hrn:node:hadronmemory.com:specs:cor:agt:060:12).
tier String Coarse tier from the server model mapping: high, mid or low. Null when unbound, unreported or unmapped; advisory, never authorization.
effort EffortLevel #4291 (hrn:node:hadronmemory.com:specs:cor:agt:060:04): the effort the worker last ran at, from its record (lastUsed.effort): a level, UNSET for the family's default, or NOT_APPLICABLE for a family with no effort control. Null when no session ever reported one.
lastUsed WorkerRunSettings! #4291 (hrn:node:hadronmemory.com:specs:cor:agt:060:04): the worker's record of the family, model and effort its session last reported, one value each and no history. It follows the session on every bind and report, is never cleared by a null, and is kept when the worker unbinds: an unbound worker is matched and started on it (family and model above stay the binding's, null when unbound). A report, not a control. Self-declared: advisory, never authorization.
launchableFamilies [String!]! Families a live host registration can launch it as (hrn:node:hadronmemory.com:specs:cor:agt:070:01).
freeForWork Boolean! Free for work (hrn:node:hadronmemory.com:specs:cor:agt:060:05).
freeFamilies [String!]! The families it is free for work as now; empty when not free.
unavailableReason AvailabilityReason Set when its own availability record makes it unavailable now.
unavailableUntil DateTime
availability WorkerAvailability #3865 — the worker's stored availability record: its reason, who set it (setBy, setByParty) and when (setAt), so a stale mark is told from a deliberate one without asking (hrn:node:hadronmemory.com:specs:cor:agt:060:02). Present for any record, in effect or not (inEffect says which); null when the worker has none. Reads nothing new: the record is the one setWorkerAvailability writes and teamAvailability returns.
unavailableFamilies [String!]! Families it could run as that are unavailable in the App now (hrn:node:hadronmemory.com:specs:cor:agt:060:03).
startedTasks [ID!]! Started tasks it is the assignee of.
pendingTasks [ID!]! Pending tasks it is the assignee of.
waitingOn [ID!]! WAITING: the open children of its started tasks.
waitingSince DateTime WAITING: when the oldest of those was created.
alarms [ID!]! YOUR_MOVE: unacknowledged alarms it has been woken on.
unreactedChildTask ID YOUR_MOVE: a finished or cancelled child it hasn't reacted to.
lastActiveAt DateTime
lastAssignedAt DateTime When it was last assigned a task; the matcher picks the least recent (hrn:node:hadronmemory.com:specs:cor:agt:060:06).
teamPlacement WorkerTeamPlacement Recorded reporting choice: REPORTS_TO means a reporting head was chosen, NO_TEAM records a choice to have none, and UNSET means no choice was recorded. Null means the value is withheld.
reportsTo AgentTaskParty #1726 — the worker it reports to; group by this for the team's structure. Read it with lastActiveAt: nothing clears a claim automatically.
reportsToRetired Boolean! #1726 — it reports to a worker that has since retired (retirement leaves the claim; the roster flags it).
checkStatus WorkerCheckStatus #2138 §3.4 (experimental) — whether it is checking its team channel as expected.
terminal WorkerTerminal #2771 — the latest terminal report a host made for it (Worker.terminal); null on the same read gate as checkStatus.
pausedUntil DateTime The worker's own stored pause timestamp, including expired history; use checkStatus for current pause state. Separate from team pause and availability.
currentTask TeamRosterTaskSummary The worker's top open assignment you can read, for display only. STARTED before PENDING, then oldest assignment (null last), creation time and id. Null when none is readable; ending a session does not clear an assignment.
heldBy WorkerHolder #2223 — the person holding this worker's name (hrn:node:hadronmemory.com:specs:cor:agt:020:09), or null: nobody holds it, the holder is deleted, or the reader fails the worker working-state gate (the same gate as Worker.heldByUserId, which is narrower than the roster's audience).
heldAt DateTime When the current hold was taken. Null exactly when heldBy is; masked the same way.

TeamRosterTaskSummary

A readable open assignment selected for display, independently of session liveness or execution eligibility.

Field Argument Type Description
id ID!
title String!
status AgentTaskStatus!

TeamTagSnapshot

Field Argument Type Description
headId ID!
label String!

TeamUtilization

Advisory current eligible workers and task-held utilization, grouped and ranked; no matching or authority effect.

Field Argument Type Description
appId ID!
computedAt DateTime!
windowHours Int!
combinations [WorkerUtilization!]!

TeamWorkItem

One team-worklog record (#947) — an externally visible work milestone (a PR opened, a branch pushed, an issue closed), append-only. The worklog is the AUTHORITATIVE PR-session join (spec cor:agt:020:03); Session.prNumber is a latest-wins display convenience. ref carries the ONE canonical spelling per artifact (github: owner/repo#N, owner/repo@sha, owner/repo:branch, owner/repo; owner/repo lowercased).

Field Argument Type Description
nodeId ID! The record node's id.
sessionId ID! The session the work is attributed to.
workerName String! Display convenience, denormalized at write: the session's bound worker name, else the attributed user's handle (pre-#974 records surface their stored personaName here).
workerId ID The Worker (named casting) behind the record, when the session was worker-bound.
tool String! The external tool the artifact lives in ('github', ...). Lowercased.
kind String! Artifact kind: pr, issue, commit, branch, or repo.
ref String! The canonical artifact ref — the equality-lookup key.
action String! What happened: opened, merged, claimed, reviewed, closed, pushed, ... (free string, lowercased).
at DateTime! When the record was made (server-stamped).
detail JSON Optional display extras (title, URL) — never filtered on.
model String The LLM model that produced the work, snapshotted at record time (#1398): an explicit report wins over the recording session's model; null on records that predate the field or were made with none — never backfilled, so null always means unknown-at-record-time.

TeamWorkItemsPage

Field Argument Type Description
items [TeamWorkItem!]!
total Int!

TickAction

Field Argument Type Description
code String! Permanent action code (hrn:node:hadronmemory.com:specs:cor:agt:110:01).
state TickActionState!
taskLoc String The readable entry's loc, including when no usable task was found.
taskUrn String The readable runnable task nearest in the woken worker's Agent chain.

Ticker

1747 — a named wake schedule owned by one team App (hrn:node:hadronmemory.com:specs:cor:agt:080:01). Its URN is hrn:ticker:ROOT:APP-SLUG:SLUG,

computed from the App and the permanent slug. Ticks are computed, not stored; nothing reads a ticker until due wakes ship.

Field Argument Type Description
tickCode String! Permanent stored action-register code; generated copies retain their template's code at generation (hrn:node:hadronmemory.com:specs:cor:agt:110:01).
registerTaskLoc String The readable Team Agent register entry's loc, without resolving any worker's task; null on absence, refusal or read failure (hrn:node:hadronmemory.com:specs:cor:agt:080:01).
id ID!
urn String The canonical URN. Null when it cannot be composed.
name String!
slug String! Permanent: a re-created name gets a new slug (engineering-2).
app App!
cadenceSeconds Int!
anchorAt DateTime!
quietHours JSON A timezone and weekly windows; null when none.
channels [Channel!]! The channels named, limited to those the reader can read. Empty means every channel the subscriber watches.
relevance TickerRelevance!
reasons [TickerReason!]! #2068 — why the ticker fires. Never empty; existing tickers are READ_TEAM_CHANNEL.
enabled Boolean!
owner ActorRef
nextTickAt DateTime The next moment this ticker ticks, quiet hours skipped; null when disabled.
lastTickAt DateTime The moment of the current tick; null when none has fired or it cannot tick.
subscribers TickerSubscriptionPage! Live subscriptions. #2931: an App key sees only those of the workers its host registers (hrn:node:hadronmemory.com:specs:cor:agt:080:22).
first Int
after String
createdAt DateTime!
updatedAt DateTime

TickerPage

2213 — one page of tickers; hasMore is whether rows remain past it.

Field Argument Type Description
items [Ticker!]!
total Int!
hasMore Boolean!

TickerSubscription

1747 — a worker subscription to one ticker (hrn:node:hadronmemory.com:specs:cor:agt:080:02).

Field Argument Type Description
id ID!
ticker Ticker!
worker Worker!
createdBy ActorRef Who subscribed the worker.
viaGrant Boolean! True when made through the may-subscribe-workers grant.
createdAt DateTime!
endedAt DateTime
endedReason TickerSubscriptionEndReason

TickerSubscriptionPage

Field Argument Type Description
items [TickerSubscription!]!
hasNextPage Boolean!
endCursor String

UninstallAgentFromAppPayload

Return shape for the uninstallAgentFromApp mutation. The Agent's per-(App, Agent, *) memories are NOT cascade-deleted (spec 023 FR-005); they persist as orphans on the now-removed AppAgent edge.

Field Argument Type Description
appId ID!
agentId ID!

UnresolvedFeedback

1607 — a node with open feedback, reported as a WARNING by mint and approval reports, never a blocker (hrn:node:hadronmemory.com:specs:cor:dmo:110:07).

Field Argument Type Description
nodeId ID!
urn String!
loc String!
openThreads Int!

UntrackedTaskItem

3125 S3: one open, untracked item of a task integration. title and labels are the tracker's text.

Field Argument Type Description
externalId String! The item's canonical URL: the externalId a claim records.
repository String! The connected repository, lower-cased.
number Int!
title String!
url String!
labels [String!]!
createdAt DateTime!
updatedAt DateTime!
linkedPullRequestMerged Boolean! True when a pull request that closes the item has merged: listed for a close check, not dropped.

UntrackedTaskItemPage

3125 S3: one page of untrackedTaskItems. total counts the whole filtered list as read: when complete is false, only what the read reached.

Field Argument Type Description
items [UntrackedTaskItem!]!
total Int!
complete Boolean!
incompleteReason String

UpdateMemoryMemberRolePayload

Field Argument Type Description
memoryMember MemoryMember!

UpdateMemoryShareRolePayload

Field Argument Type Description
memoryShare MemoryShare!

UrnResolution

Result of resolving a Hadron URN to the ids a client needs to navigate to the resource's canonical page. Powers the portal's /app/u/<urn> redirect route (hadron-portal#262).

kind is the URN's type segment: memory | node | agent | org | app | user | apprun | worker | noderev | aiconf (#3857: an AI service config, behind the same gate as aiServiceConfig(ref:); an unreadable config answers null, as a missing one does, hrn:node:hadronmemory.com:specs:cor⚱010:01). id is the resolved entity's primary id. memoryId is set only for nodes (their owning memory), organizationId for apps, app runs, and workers (their owning org), and for an aiconf (#3857) the org that owns it or its App or Agent (null for a server-owned config or a user-owned App or Agent) — both are the extra ids those resources' canonical routes require.

Field Argument Type Description
kind String!
id ID!
memoryId ID
organizationId ID
fragment String Set to 'data' when the resolved URN named a #data fragment of its parent node/apprun (#696); null otherwise.

UsageActivityBucket

One time bucket of read+write activity (#796).

Field Argument Type Description
date String! Bucket start as YYYY-MM-DD, in the requested timeZone. Deliberately String and NOT DateTime (#205): it is a calendar-day label in the caller's zone, not an instant — rendering it as a UTC timestamp would shift buckets across the date line.
reads Int!
writes Int!

UsageEvent

Field Argument Type Description
id ID!
type String!
nodeLoc String
memoryId String Memory the event is attributed to (#796). Stored at write time, so it outlives the node — null only for events written before the backfill whose node was already deleted, or paths with no memory in scope.
actionArgs JSON
appId String Caller identity — the App that authored this event.
sessionId String
model String
tokensIn Int
tokensOut Int
userId String
organizationId String
provider String
keyOwnerType String Owner level of the API key that served the call (HADRON_SERVER means platform-paid; anything else is BYOK).
costMicroCents String Provider cost snapshot in micro-cents (1e-8 USD), as a base-10 integer string. Null when the (provider, model) pair is unpriced.
createdAt DateTime!

UsageEventPage

2212 — one page of usage events in the caller's readable memories.

Field Argument Type Description
items [UsageEvent!]!
total Int!
hasMore Boolean!

UsageSummaryEntry

Field Argument Type Description
nodeLoc String!
type String!
count Int!

User

Field Argument Type Description
sharedOrganizations SharedOrganizationsPage Live shared memberships only; null for unsupported viewers or deleted users, empty for no intersection. Default 20, cap 200, nonnegative offset, organization id order. Impersonation stays in its one organization. Pages are live across requests.
limit Int
offset Int
id ID!
handle String
policy JSON User-layer action-policy link (cor:acl:040:02, #510) — constrains runs made on the user's behalf. Null = no restriction, or hidden from viewers without personal-field access. Self-authored via updateMyPolicy.
urn String Canonical `hrn:user:` URN (spec cor:urn:010:01). Computed from the handle; null for a handle-less user and for a user whose handle is not-URN-legal (neither has a URN).
githubId Int Numeric GitHub account id (#2574, hrn:node:hadronmemory.com:specs:cor:acl:070:01). Personal tier, like name and email: null for a viewer who is not the user, a platform admin, or a co-member of one of their orgs.
githubUsername String GitHub username (#2574, hrn:node:hadronmemory.com:specs:cor:acl:070:01). Identity tier: visible to any signed-in viewer, and a public search key (hrn:node:hadronmemory.com:specs:cor:acl:070:02).
googleId String Google account subject id (#837). Opaque provider identifier, never an address. Withheld (null) from a viewer who is not the user themselves, a platform admin, or a co-member of one of their orgs — the same #384 gate that name/email use. Load-bearing for duplicate-account triage: mergeUsers adopts a source provider id only where the target column is null, and identityProvider records only which provider CREATED the row, so it cannot be used to infer this (a GITHUB row may carry a linked googleId).
appleId String Apple account subject id (#837). Same gate and rationale as googleId.
identityProvider String Account metadata, visible to self, platform admins, and co-members.
externalId String
externalAppId String
linkedAt DateTime
name String
email String
avatarUrl String Avatar image URL (#2574, hrn:node:hadronmemory.com:specs:cor:acl:070:01). Identity tier: visible to any signed-in viewer.
roles [Role!]! Platform roles; an empty list is returned to viewers without personal-field access.
maxReferrals Int
appMemberships [AppMember!]! 008-agent-installation: User-App memberships. Resolves to a non-empty list only when the queried User is the authenticated user (mirrors the User.agentSubscriptions resolver-side gate from 005).

UserApiKey

025-oauth-for-mcp: user-scoped bearer-token credential. Mirrors the AppKey shape but resolves to a User instead of an App. Surfaced to the portal revocation UI (Phase 3) so users can audit + revoke their own keys. userId is intentionally absent — for self-service v1 the caller is always the owner; admin-tooling auditability is out of scope (see contracts/graphql-mutations.md, PR-137 delta D1).

Field Argument Type Description
id ID!
keyPreview String!
label String
createdAt DateTime!
lastUsedAt DateTime
revokedAt DateTime
hiddenAt DateTime #2298: when the owner hid this revoked key from their default list; null when visible. Display state only: it never affects validity, revocation or lineage.
issuedVia String Issuance identity: portal for direct sign-in issuance, or oauth:<client_id> for OAuth issuance. A key minted by a key inherits that credential's issuance identity. Powers source labels in the revocation UI.
mintedByKeyId ID Authenticated key that minted this key. Null for direct issuance, unknown legacy ancestry, or a minting key its user has since deleted (#2659, hrn:node:hadronmemory.com:specs:cor:dmo:070:03: the break is recorded once, in that deletion's record); historical parents are never inferred.
oauthScopes [String!]! Immutable OAuth scopes bound to this credential. Empty means an unrestricted portal/legacy key rather than an OAuth-scoped key.

UserApiKeyCreateResult

Returned once at creation — the raw key is never stored. Renamed from PR 137's UserApiKeyCreated for Result-suffix consistency; nested field is userApiKey, not key (PR-137 delta D2).

Field Argument Type Description
userApiKey UserApiKey!
rawKey String!

UserApiKeyDeletion

2659 (hrn:node:hadronmemory.com:specs:cor:dmo:070:03, ruling 0007): the one

append-only record a user's deletion of their own API key leaves behind. Names the key (its id and masked preview) and when; never its secret or its hash.

Field Argument Type Description
id ID! The deletion record's id.
keyId ID! The deleted key's id. The key itself no longer exists.
keyPreview String! The deleted key's masked preview (its last characters).
revokedKeyIds [ID!]! The keys this delete revoked: the key itself when it was live, with its live subtree (hrn:node:hadronmemory.com:specs:cor:aut:010:02 rule 9). Empty when the key was already revoked.
mintedKeyIds [ID!]! The keys the deleted key had minted. They were not deleted: they stay, revoked, with no parent (mintedByKeyId null).
deletedAt DateTime!

UserApiKeyPage

2213 — one page of the caller's own user API keys.

Field Argument Type Description
items [UserApiKey!]!
total Int!
hasMore Boolean!

UserInvitation

Invitation to join the platform (and optionally an organization)

Field Argument Type Description
id ID!
slug String!
senderUserId String
sender User
organizationId String
organization Organization
memberRole Role!
name String
email String
githubUsername String
maxActivations Int
expiresAt DateTime
acceptedAt DateTime
createdAt DateTime!
activationCount Int!

UserMergeConsentRequest

Field Argument Type Description
proof String!
expiresAt DateTime!

UsersPage

Field Argument Type Description
items [User!]!
total Int!

WakeReason

Field Argument Type Description
action TickAction The tick's role-task guidance, gated for the reader on every read; null for other reasons (hrn:node:hadronmemory.com:specs:cor:agt:080:23).
kind WakeKind!
ticker Ticker
tickDueAt DateTime #2790 (hrn:node:hadronmemory.com:specs:cor:agt:080:23) — set for kind TICK only, null for MENTION, TASK and STOP: the time of THIS ticker's oldest tick the worker has not acknowledged, up to the tick that fired. It is per reason, so a wake with an old mention and a fresh tick, or ticks of two tickers, shows each tick's own time; `anchorAt` stays the earliest over all reasons (hrn:node:hadronmemory.com:specs:cor:agt:080:27) and is at or before every one of these. Computed at read time from the worker's acknowledged tick, never stored: a tick that joins an outstanding wake (hrn:node:hadronmemory.com:specs:cor:agt:080:12) leaves it at the oldest unacknowledged tick, not the joining one.
task DueTaskReason Set for kind TASK.
stop DueStopReason #2022 — set for kind STOP.

WebPoll

A page-monitor watch (#1562): the hadrontool-webfetch job behind a run's web_poll_start, as the org's admins see it outside a run. url is the query- and fragment-free ledger URL, never the one the sidecar fetches, and no credential material is returned.

Field Argument Type Description
jobId ID!
status String! An open string supplied by hadrontool-webfetch. Values seen include active and cancelled; these examples are not exhaustive, and clients must tolerate other states.
url String!
appId ID!
sourceRunId ID! The run that started the watch.
createdAt DateTime!
nextRunAt DateTime
expiresAt DateTime!
lastCheckedAt DateTime
lastTriggeredAt DateTime
triggerCount Int!
consecutiveFailures Int!

WebPollsPage

One page of org-bound watches in jobId order. Default 20, clamp 1–100. Authenticated jobId keyset cursors survive deletion of the boundary row. Offset is a separate option. total counts current org-bound watches. hrn:node:hadronmemory.com:specs:cor:api:120:04.

Field Argument Type Description
items [WebPoll!]!
total Int!
hasMore Boolean!
nextCursor String

Worker

A Worker (#974, cor:dmo:050:11) — the named casting of an installed Agent into an App: 'Iris', the backend-engineer agent cast into the eng-team App. The Agent carries the reusable persona dressing; the Worker is the local named identity that does attributable work. Names are unique per App, case-insensitively, forever (retirement and uninstall never free them — cor:agt:020:02); rows survive the agent's uninstall. A Worker is addressable by its id or by the computed urn below (#991).

Field Argument Type Description
promptLintWarnings LintWarningPage Current lint of the compiled revision recorded for the open session; null when unavailable.
first Int
after String
availability WorkerAvailability #3865 — the worker's stored availability record: reason, who set it (setBy, setByParty) and when (setAt), the same record `TeamRosterEntry.availability` and `teamAvailability` return (hrn:node:hadronmemory.com:specs:cor:agt:060:02). Worker-internals field: null for a caller who may not see them, and null when the worker has no record.
id ID!
appId ID!
appUrn String The App's canonical URN (the same value App.urn returns, e.g. hrn:app:acme.com:team), as a scalar identity suitable for cross-App worker lists. PROFILE field (#1149, hrn:node:hadronmemory.com:specs:cor:dmo:050:11): null only for a caller who may not see this worker's profile. This intentionally does not return the App object, whose nested keys and members have a narrower read audience.
appName String #1149 — the App's display name ('Team'), so a worker's profile page can say whose staff it is without the App object. PROFILE field (hrn:node:hadronmemory.com:specs:cor:dmo:050:11): readable by any signed-in user who names the worker; null for a caller who may not see its profile.
ownerName String #1149 — the owner atom of the worker's URN: the user handle of a user-owned App or the organization slug of an org App, and nothing more (no display name, no email). PROFILE field, gated like appName; also null when the App's URN predates the grammar-v2 shape (as urn).
agentId ID!
name String! The worker's name ('Iris') — the identity every surface renders.
slug String! The URN atom, derived from the name at cast time and permanent thereafter (#991). Lowercased, sanitized to the URN slug charset, and iterated ('iris', 'iris-2', …) until free within the App — so deriving it NEVER refuses a cast, and the name collision stays the only allocation failure a caller sees (cor:agt:020:02).
urn String hrn:worker:<root>:<app-slug>:<slug> (#991) — computed from the App's URN plus `slug`, not stored. Accepted anywhere a workerRef is taken, and resolvable via Query.resolveUrn, so a client can address a worker without holding its id. Null only when the App's URN predates the flat grammar-v2 shape this arity requires.
portalUrl String #1026 — the portal link that opens this worker, mirroring Node.portalUrl (#881), so a worker signing an artifact under #1008 hands over a URL instead of assembling one out of a URN spelling the /app/u route may not resolve. Built from the SAME URN the urn field returns, so the two cannot diverge. Null on both arms and neither is an error: no configured portal origin means no link (a link to the wrong host is worse than none), and an App URN the fixed arity cannot take means no URN to build one from.
role String The cast-list role this filling answers ('backend-engineer').
repos [String!]! #1024 — the repo affinity of this worker's ROLE, resolved so a client that already holds the worker needs no second round-trip to teamRoles. Clients may use it to warn on a role/repo mismatch at session start; the server does not enforce a repo-affinity refusal. WORKING-STATE field: behind the worker read gate and masked to [] on deny, like memoryId and the holder — Session.worker reaches a Worker through a wider gate that admits any org member and survives a user leaving the App, so an ungated field would publish a team's repo list through any historical session. Masking to [] costs nothing, because empty already means "no affinity, never warn": a denied caller simply gets no warning, which is the safe direction for a signal that must never become a refusal. Same reason a worker with no role, a role with no definition, or an unreadable system memory all answer [] rather than erroring.
signature String Per-worker signature template, masked for nonreaders (hrn:node:hadronmemory.com:specs:cor:agt:040:04).
trailer String Per-worker commit trailer template, masked for nonreaders (hrn:node:hadronmemory.com:specs:cor:agt:040:04).
signatureLint LintWarningPage #2048 — whether the signature and trailer above carry the worker link, as they hold now (hrn:node:hadronmemory.com:specs:cor:agt:040:13). Same gate as signature and trailer: null (unavailable, not "no warnings") for a caller who may not see them, and on a fault. A warning never blocks an edit.
first Int
after String
bootPromptRef String #2045 — the canonical URN of the compiled boot prompt this worker's pointer names now (set for customised workers only). Null when no pointer is set OR when the caller may not see it (WORKING-STATE field, behind the worker read gate): null is not proof that no pointer exists.
bootPromptTargetDeleted Boolean #2045 — whether the pointer's target is deleted (soft or hard): true / false, and null when no pointer is set or the caller may not see it. Same gate as bootPromptRef. Nothing is served from a deleted target (R27).
bootPromptServe BootPromptServeOutcome #2708 — what this worker's NEXT bind would be served now (hrn:node:hadronmemory.com:specs:cor:agt:040:10): its own pointer, else the install's, else the Agent's. Computed by the resolver the bind itself uses, so the bind is refused exactly when refusal is set and records exactly the revision served names. Only the boot prompt is judged: a bind can still be refused for other reasons (a retired worker, a held worker). Null when the caller may not see it (same gate as bootPromptRef, WORKING-STATE), which is judged before anything is resolved.
memoryId ID The worker-scoped working memory in the App's container (null until provisioned).
heldByUserId ID #1050 — the human HOLDING this name, or null when nobody does. A name is held by a person, not by a live session: expiry, a reap, or a closed chat session never free it, and only an explicit release does. This is what separates the two meanings of "taken" — HELD is whose name it is, while a live session is only ever a question about your own worker. WORKING-STATE field, behind the worker read gate and masked to null on deny — like memoryId, and NOT like name/role/urn. Session.worker reaches a Worker row through a wider gate that admits any org member and survives a user leaving the App, so an ungated holder would let a former member read current staffing off a historical session.
heldAt DateTime When the current hold was taken. Null exactly when heldByUserId is — and likewise masked on deny. #1034: "taken" here is the HOLD's timestamp, unrelated to `WORKER_TAKEN` (a live worker session) and to `TeamRoleName.taken` (a name allocated in the register). Three senses of one word across two types.
teamPlacement WorkerTeamPlacement Recorded reporting choice: REPORTS_TO means a reporting head was chosen, NO_TEAM records a choice to have none, and UNSET means no choice was recorded. Null means the value is withheld.
reportsToWorkerId ID #1726 — the one Worker this worker reports to: a non-retired Worker of the same App, never itself, never a cycle. Null reports to nobody. A property of the casting, not of a session, so binding or ending a session leaves it alone. Changed with setWorkerReportsTo (or reportsTo at startSession); every change is a `worker.reports-to` team event. Masked on deny, like heldByUserId.
reportsTo Worker #1726 — the Worker named by reportsToWorkerId; masked likewise.
reportsToRetired Boolean! #1726 — true when this worker reports to a worker that has since retired (a stale claim nothing clears automatically).
hasLiveSession Boolean hadron-cli#487 — whether anyone is DRIVING this name right now. Not availability: availability is the HOLD above (`cor:agt:020:09`), and an ended or idle session never frees a name. This says only whether someone is mid-stint, which is the question a coordinator asks about a name already theirs. Conflating the two is the CLI bug this field exists for. #1114 — COMPUTED, never stored: an unended session driven inside its type's idle window, with no promised hard expiry at or before now. An open row alone is insufficient. Inactivity does not end the session or release a human-held name. An eligible act may resume a lapsed session; a dormant or terminal session cannot be revived by an agent act. Uses the SAME predicate startSession refuses WORKER_TAKEN on (`cor:agt:020:11`) — a reader must not be told a worker is busy that a binder can take, and since #1114 that is load-bearing rather than tidy: with nothing ending abandoned sessions, an `endedAt IS NULL` gate would refuse a bind forever and leave force as the only route. Nullable BECAUSE of the read gate, not because the answer is unknown: this is a working-state field like heldByUserId, masked to null on deny rather than answering false, which would state a fact the server never computed.
family String #1707 — the model family of this worker's binding (hrn:node:hadronmemory.com:specs:cor:agt:060:04): its newest open session's family. It follows the binding, not activity: a quiet session keeps it, and it is cleared when the session ends or replaced by a newer bind. Null when unbound, when the binding reported none, or on the same read gate as hasLiveSession. A matching input, never an authorization input.
model String #2252 — the model this worker's binding last reported: its newest open session's, the same fold, gate and lifecycle as family. Null when unbound, when the binding reported none (an older session's is never inherited), or on the same read gate as hasLiveSession. Self-declared: advisory, never authorization.
modelReportedAt DateTime #2252 — when model was self-reported (a bind, a resume or an updateSession carrying a model; a repeat of the same model counts). Null when the session never reported one. A report time, not verified detection.
modelGroups [String!] Current matching model-group names, resolved live from the Team Agent and App overrides. Empty without a reported model or match; null when working-state access is denied. Advisory only, never authorization (hrn:node:hadronmemory.com:specs:cor:agt:060:12).
tier String #2252 (R189) — the coarse tier of model from the platform's one model-to-tier mapping: high (opus-class), mid (sonnet-class), low (haiku-class); null when the model is unmapped (no guessed equivalence for another family). Advisory: a coordinator's reading aid, never an authorization or routing input in this slice.
lastUsed WorkerRunSettings #4291 (hrn:node:hadronmemory.com:specs:cor:agt:060:04) — the worker's record of the family, model and effort its session last reported: one value each, no history. It follows the session on every bind and report (whoever made the change), is never cleared by a null, and is kept when the worker unbinds, when family and model above are null: an unbound worker is matched on it, and a start launches it with these unless the task names its own. A report, not a control: no edit makes a running session adopt a value. Null on the same read gate as hasLiveSession. Self-declared: advisory, never authorization.
lastActiveAt DateTime hadron-cli#487 — when this worker was last DRIVEN, over every session it has ever had. Null for a worker nobody has ever bound, and that null is the point: a casting nobody picked up renders identically to one worked yesterday on every surface today, so a coordinator can dispatch into a channel no one reads and get no signal at all. The instant is the platform's one derivation of session activity — the greatest of startedAt, updatedAt, and the newest attributed usage event — so it agrees with the takeover prompt and with the idle window hasLiveSession is derived from (#1114: that window DESCRIBES a session, it no longer ends one). Masked to null on deny, like heldByUserId.
checkStatus WorkerCheckStatus #2138 §3.4 (experimental) — whether this worker is checking its team channel as expected, derived at read time. Masked to null on the same read gate as hasLiveSession.
terminal WorkerTerminal #2771 (proposed hrn:node:hadronmemory.com:specs:cor:agt:070:09) — the latest terminal report a host made for this worker. Stored, decides nothing; judge its age from checkedAt. Null until a host reports, and masked to null on the same read gate as checkStatus.
agent Agent The role-agent behind the casting. DETAILS tier (#1149, hrn:node:hadronmemory.com:specs:cor:dmo:050:11): resolved for whoever the Agent's own visibility admits (PUBLIC, else READER on the Agent), evaluated per read; null otherwise and for a deleted Agent.
app App The App whose staff this casting fills. Never part of a worker's profile (#1149): null unless the caller may read the App itself.
prompt String The worker's boot prompt: the approved revision of the compiled boot prompt a bind of this worker is served (hrn:node:hadronmemory.com:specs:cor:agt:040:07), with the platform variables filled. Null when no prompt can be served.
renderedSignature String #2969 (hrn:node:hadronmemory.com:specs:cor:agt:040:04): the worker's signature as the served boot prompt fills it, the platform variables substituted (session.llmModel is the empty string when no model is recorded). Reaches exactly the callers prompt reaches; null for anyone else, with no refusal.
renderedTrailer String #2969: the worker's trailer, filled as renderedSignature is, for the same callers.
continuity WorkerContinuity #1029 — what a fresh binding of this worker inherits from the last one. Returned by startSession alongside the boot briefing (binding is briefing, so binding is handoff) and by the worker read, which is the recovery path after a context compaction — the reader who has most lost the handoff and least knows one exists. Working-state field: behind the worker read gate, masked to null on deny, like prompt/memoryId.
createdAt DateTime!
createdBy String Who cast this worker. WORKING-STATE field (#1149): null for a caller who may see only the worker's profile.
retiredAt DateTime Retirement instant — a retired worker stops authoring and takes no new sessions; the name stays reserved.
retiredBy String Who retired this worker. WORKING-STATE field (#1149), masked like createdBy.
leaveAlone Boolean #4224 (S3 of #4229): the leave-alone marker (setWorkerLeaveAlone). A host's sweep observes and reports a marked worker and never starts, stops or repairs it. WORKING-STATE field (#1149, hrn:node:hadronmemory.com:specs:cor:dmo:050:11): null for a caller who may see only the worker's profile.
leaveAloneReason String Why the worker is marked leave-alone, when a reason was given. WORKING-STATE field (#1149), masked like createdBy.
leaveAloneBy String The user who marked the worker leave-alone. WORKING-STATE field (#1149), masked like createdBy.
leaveAloneAt DateTime When the worker was marked leave-alone; null when it is not marked. WORKING-STATE field (#1149), masked like createdBy.
servedPrompt ServedPrompt #2047 / hrn:node:hadronmemory.com:specs:cor:agt:040:03: the boot prompt served to this worker's open session. Readable by whoever may read the worker's internals; null for anyone else, and when no session is open.

WorkerAvailability

1706 — one worker's availability for work (hrn:node:hadronmemory.com:specs:cor:agt:060:02). A worker with

no record is available.

Field Argument Type Description
worker AgentTaskParty!
state AvailabilityState!
reason AvailabilityReason Set exactly when unavailable.
until DateTime When an unavailable record lapses. A passed until reads as available at once; within a minute the record is rewritten to AVAILABLE, set by LAPSE, and one availability.changed event records it (hrn:node:hadronmemory.com:specs:cor:agt:060:02).
setAt DateTime!
setBy AvailabilitySetter!
setByHostId String #1709 — the host that set it, when setBy is HOST.
setByParty AgentTaskParty Who acted, when a worker or a person set it; null when the stall rule or a lapse did.
inEffect Boolean! Whether this record makes the worker unavailable right now: unavailable, not lapsed, and (for STALLED) the worker has not acted since it was set (hrn:node:hadronmemory.com:specs:cor:agt:060:07).

WorkerCheckStatus

2138 §3.4 — a worker's check status. A worker HAS A TASK when an open task is

assigned to it or its Agent has usesTasks: false. The OVERDUE clock runs from the latest of lastCheckedAt, its newest open assignment, its live session's start and the end of its own pause.

Field Argument Type Description
status WorkerCheckState!
pendingReason WorkerPendingReason Set only when status is PENDING.
noSessionReason WorkerNoSessionReason #3077: set only when status is NO_SESSION.
lastCheckedAt DateTime When it last checked the App's team channel through its own session; null if never.

WorkerContinuity

1029 — the continuity a worker carries between stints.

Handoffs are ordinary nodes in the worker's working memory, so a client walks the whole sequence through the node surface. This type exists for the ONE handoff that cannot be discovered: the newest, which a fresh session does not know to look for.

Field Argument Type Description
status WorkerContinuityStatus!
handoff Node The newest handoff node, or null when the worker has none. Present even when status is MISSING — a stale handoff is still the best available account of where this worker got to, and withholding it helps nobody.
previousSession WorkerContinuitySession The worker's most recent ENDED session, as a SANITIZED projection — the three facts continuity needs, and deliberately not the Session object. The worker read gate that admits this field is WIDER than the session read gate: an AppMember who is not an org member passes the first and fails the second. Returning a Session here would hand them another driver's transcriptPath, host, repo and summary through its field resolvers, which assume the outer query authorized them (#552 / #983).

WorkerContinuitySession

1029 — the previous stint, reduced to what a successor needs to know: which

session it was, when it ended, and whether the server reaped it. Not a Session, on purpose (see WorkerContinuity.previousSession).

Field Argument Type Description
id ID!
endedAt DateTime
autoExpiredAt DateTime Set when the #930 reaper ended it — nobody closed this stint deliberately.

WorkerDesiredState

4224: one worker's desired state on one host, with the setup the host needs to start it.

Field Argument Type Description
workerId ID!
name String!
lifecycle AgentLifecycle! The lifecycle of the worker's Agent.
desired DesiredRunState RUNNING or STOPPED; null exactly when reason is LEAVE_ALONE or SWEEP_OFF, where nothing is desired and a reader acts on nothing.
reason DesiredStateReason!
wouldBe DesiredRunState Set exactly when desired is null: the state the worker would have without the marker, or with the sweep on.
wouldBeReason DesiredStateReason The reason for wouldBe; never LEAVE_ALONE or SWEEP_OFF. Null when wouldBe is.
openSessionId ID The worker's open session (not ended), or null. Open, not live: a quiet session is still open.
family String! The model family the host registered the worker to run as.
worktrees [String!]! The worker's existing worktrees on this host, as the host names them; empty when it has none.

WorkerHolder

2223 — a sanitized identity for the person holding a worker's name. A closed projection, never User:

User's default-resolved tail (policy, identityProvider, externalId, githubId, roles, maxReferrals) must not come along (hrn:node:hadronmemory.com:specs:cor:acl:110:01). The same four fields as ReleasedFromUser.

Field Argument Type Description
id ID!
handle String
urn String Canonical hrn:user:<handle> URN (hrn:node:hadronmemory.com:specs:cor:urn:010:01). Null for a handle-less user.
name String Behind the #384 gate, as User.name: the holder, a platform admin, or a co-member of one of their orgs. Null both when withheld and when unset, so a masked name cannot be told from an unnamed user.

WorkerLeaveAlone

4224: a worker's leave-alone marker after setWorkerLeaveAlone. reason, by and at are null when the worker is not marked.

Field Argument Type Description
workerId ID!
leaveAlone Boolean!
reason String
by String The user who set the marker.
at DateTime

WorkerRunSettings

4291 (hrn:node:hadronmemory.com:specs:cor:agt:060:04): a worker's last-used run settings. Each is null until a session of the worker reported it.

Field Argument Type Description
family String
model String
effort EffortLevel

WorkerTerminal

2771 (proposed hrn:node:hadronmemory.com:specs:cor:agt:070:09) — a worker's latest terminal report, stored as the

server built it. It decides nothing (no check status, availability, matcher, stall rule or alarm). Judge its age from checkedAt and reportedAt. Null until a host first reports; null to a reader without the Working-state gate.

Field Argument Type Description
host WorkerTerminalHost!
status WorkerTerminalState!
prompt WorkerTerminalPrompt!
reason WorkerTerminalReason Required for locked and dark, null otherwise.
lastTurnAt DateTime
checkedAt DateTime! When the host classified the terminal.
reportedAt DateTime! When the server stored the report.
contextTokens Int #4225 — the size of the worker's context in tokens, as its host measured it. Null when the host could not measure it (never 0), and on a report stored before hosts sent it. Shown only: it decides nothing.
contextMeasuredAt DateTime #4225 — when the host measured contextTokens; judge its age from this. Null exactly when contextTokens is.
repair WorkerTerminalRepair #4247 — what the host did about this dark worker, stored for RELAUNCH_REFUSED and RELAUNCH_FAILED only. Null for the other outcomes (they are not stored) and when the report carried none; the next report replaces it.
repairReason WorkerTerminalRepairReason #4247 — why the relaunch was refused or failed. Null exactly when repair is.
repairAttempt Int #4247 — the relaunch's attempt number, at least 1. Null exactly when repair is.

WorkerTerminalHost

2771 — the host that made a worker's latest terminal report: its id from the key, its label from its registration.

Field Argument Type Description
id String!
label String!

WorkerTerminalRef

2771 — a worker by id and URN only: a host key is not given a Worker object.

Field Argument Type Description
id ID!
urn String!

WorkerTerminalRefusal

2771 — a report not stored for one worker: WORKER_NOT_FOUND, TERMINAL_REPORT_STALE, REPAIR_NOT_DARK, REPAIR_ATTEMPT_INVALID or REPAIR_REASON_INVALID.

Field Argument Type Description
worker String! The worker as the host named it.
code String!

WorkerUtilization

One current family/tier/role combination. Unknown tier has its own null row; retired workers are excluded.

Field Argument Type Description
family String!
tier String
role String
eligibleWorkers Int!
busyWorkers Int!
utilization Float!
saturated Boolean! Slice 1: true only for zero eligible workers (then utilization=1). Failure-only saturation reads false until the deferred match-outcome integration; no alarm is emitted by this read.

WorkerWakeSettings

1747 — a worker wake settings (hrn:node:hadronmemory.com:specs:cor:agt:080:03).

Field Argument Type Description
worker Worker!
mentions MentionWake!
pausedUntil DateTime A pause belongs to the worker, not to a session.
subscriptions [TickerSubscription!]! Live subscriptions.
effectiveCadenceSeconds Int The fastest live subscription on an enabled ticker; null when none.
dormant Boolean! None of the worker's sessions has had activity within the App's dormancy period (hrn:node:hadronmemory.com:specs:cor:agt:080:07). A dormant worker is never woken.

WorkersPage

Field Argument Type Description
items [Worker!]!
total Int!

Inputs

AccountUsageMoveWorkerInput

Field Type Description
worker String!
toAccount String!
toHost String Needed only when the target label has history from more than one host or family.
toFamily String

AccountUsageWhatIfInput

3820 — exactly one of the two.

Field Type Description
addWorkers Int Add this many workers (1 to 50) to the account, each burning the account's per-worker estimate.
moveWorker AccountUsageMoveWorkerInput Move one worker from the projected account to another; it takes the source's per-worker estimate with it.

ActInstructionInput

A typed instruction reference, never instruction text.

Field Type Description
kind ActInstructionKind!
ref String! TASK and TEAM_CHAT_MESSAGE use a caller-readable same-App URN, including one the worker authored. LIVE_CHAT is a self-asserted opaque client address, 1-512 UTF-16 code units, without whitespace. A person's present claim is validated too, but never recorded as an instructed act.

AgentFilter

Filter for the uniform agents() list (#473). Clauses AND-combine.

Field Type Description
type AgentType
visibility AgentVisibility
ownedByMe Boolean #782 — true restricts the list to the caller's OWN user-owned (org-less) agents: organizationId IS NULL AND ownerUserId = the caller. For ALL callers INCLUDING platform ADMIN/OWNER (owner scope is never an admin-bypass surface), mirroring the owner-only personal/private memories slice. Org-less by definition, so orgId is not consulted. App-key callers (no user context) get an empty page. Powers the portal's "My agents".

AgentTaskFindingInput

2662: give every id, or none for platform F1/F2/... ids in list order. Ids unique, 1–32 letters/digits/_/-. Text at most 2,000 Unicode code points; no trimming.

Field Type Description
id String
severity AgentTaskFindingSeverity!
text String!

AgentTaskHandBackInput

2651: the reason a hand-back gives (hrn:node:hadronmemory.com:specs:cor:agt:050:29).

Field Type Description
code AgentTaskHandBackCode!
text String Optional, up to 2,000 characters after trimming; blank is none. Stored on the task, never put into an event.

AgentTaskPartyInput

Names exactly one task party: a worker of the task's App (its id, URN or name), or a person who participates in the App (their user id or handle).

Field Type Description
worker String
user String

AgentTaskReferenceFilter

2649: agentTasks(reference:) matches tasks carrying a reference with exactly this target (1 to 512 characters, else BAD_USER_INPUT), and this kind when given. The label is ignored.

Field Type Description
kind AgentTaskReferenceKind
target String!

AgentTaskReferenceInput

2649 (hrn:node:hadronmemory.com:specs:cor:agt:050:01): one reference to set. target must have its kind's form and be

at most 512 characters, with no whitespace or control characters (a URL is written scheme://host, with no backslash); label at most 120 (empty means none). A list of more than 20, or any item that fails, is refused BAD_USER_INPUT and nothing is written.

Field Type Description
kind AgentTaskReferenceKind!
target String!
label String

AgentTaskRequirementsInput

Field Type Description
roles [String!] Any one listed role suffices. Empty sets are refused. Give role or roles, not both.
team String Lead worker (id, URN or name) of this App. Pool: lead, descendants and workers reporting to nobody.
role String
familyIn [String!] Model families the assignee must run as. Give this or familyNotIn, not both.
familyNotIn [String!]
excludeWorkers [String!] Workers of this App (id, URN or name) the matcher must not pick.
minTier String The lowest model tier the assignee may run at: low, mid or high, in that order (hrn:node:hadronmemory.com:specs:cor:agt:060:06). A worker below it, or whose tier is unknown, is never matched; the lowest sufficient tier wins. There is no maximum.
modelGroupIn [String!] Model groups of the App (hrn:node:hadronmemory.com:specs:cor:agt:060:12) the assignee's model must be in at least one of. A name no group of the App carries is refused. A worker with no model is in no group, so it never matches.
modelGroupNotIn [String!] Model groups of the App (hrn:node:hadronmemory.com:specs:cor:agt:060:12) the assignee's model must be in none of. A name no group of the App carries is refused. A worker with no model is in no group, so it passes.

AgentTaskResultInput

Field Type Description
outcome String! One word (letters, digits, underscore, hyphen or dot; up to 64 characters), e.g. succeeded or failed. It is copied into the event stream, which never holds free text. When the team has an outcome set (#2652, schema:task-outcomes; hrn:node:hadronmemory.com:specs:cor:agt:050:30) it must be one of the set (TASK_OUTCOME_NOT_IN_SET); an unusable set refuses every finish (TASK_OUTCOME_SET_UNUSABLE).
summary String
evidence String
findings [AgentTaskFindingInput!] #2662: optional immutable findings, at most 100 (hrn:node:hadronmemory.com:specs:cor:agt:050:30); omitted/null preserves legacy finish.

AgentTaskRunSettingsInput

4291 (hrn:node:hadronmemory.com:specs:cor:agt:050:01; decision record run-settings-are-not-worker-identity) — a task's own run

settings: what a start for it launches. Anything left out falls back to the worker's last used (Worker.lastUsed), so a missing value is never a refusal. They are run settings, not requirements: a worker that is already running takes the task under its session's settings (AgentTask.appliedRunSettings shows them), and a task that must run on a family says so with requirements.familyIn. For a short-lived worker with no open session the launch applies them, so the matcher judges familyIn, familyNotIn and minTier against them (hrn:node:hadronmemory.com:specs:cor:agt:060:06).

Refused TASK_RUN_SETTINGS_INVALID, with extensions.reason: BAD_VALUE (a field that is not its token), EFFORT_NOT_A_REQUEST (NOT_APPLICABLE), MODEL_AND_TIER (both named), MODEL_OUTSIDE_FAMILY (an exact model of another family than the one named), FAMILY_EXCLUDED (the family, named or implied by the model, is outside requirements.familyIn or inside familyNotIn), TIER_BELOW_MINIMUM (the tier, or the exact model's tier, is below requirements.minTier).

Field Type Description
family String A model family token, e.g. claude, codex or glm.
model String An exact model name (letters, digits, '.', '_' or '-'; at most 128 characters). Give this or tier, not both.
tier String A generic tier instead of a model: high, mid or low. The host's launcher maps it to the family's model.
effort EffortLevel A generic effort; the launcher maps it to the family's own value. NOT_APPLICABLE is a report, not a request, and is refused.

AgentTaskStallScheduleInput

An omitted field keeps its value; null returns it to the platform default. Each window is 1 to 10080 minutes; hostLapseCheckIns is 2 to 10; sessionEndGraceMinutes is 1 to 1440; hostReportTimeoutMinutes is 5 to 1440.

Field Type Description
notStartedMinutes Int
noProgressMinutes Int
ownerReactionMinutes Int
assignmentMinutes Int
hostLapseCheckIns Int
sessionEndGraceMinutes Int
hostReportTimeoutMinutes Int

AgentTickerTemplateInput

Field Type Description
name String!
cadenceSeconds Int!
quietHours JSON
relevance TickerRelevance
reasons [TickerReason!] Absent = [READ_TEAM_CHANNEL]; an empty list is refused.

AgentTickerTemplatePatch

Absent fields are unchanged. Use clearQuietHours to remove the quiet hours.

Field Type Description
name String
cadenceSeconds Int
quietHours JSON
clearQuietHours Boolean
relevance TickerRelevance
reasons [TickerReason!] An empty list is refused.

AiServiceConfigFilter

Filter for the uniform aiServiceConfigs() list (#473) — the owning entity. Omitted entirely, the list is the platform ADMIN/OWNER's cross-owner view of every config; non-admin callers MUST filter by owner (org ADMIN of the owning org, mirroring the management-surface gate).

Field Type Description
ownerType AiConfigOwnerType!
ownerId ID! The owning entity — accepts ID or URN (HADRON_SERVER: ID only).

AiServiceConfigTestOverride

1378: values to test INSTEAD of the saved ones — e.g. an edited form before

it is saved. Never stored. Each is validated exactly as a write would be.

Field Type Description
provider String
model String
endpoint String Omitted = the saved endpoint; null or empty = the provider default.
apiStyle AiApiStyle Omitted = the saved style; null = the provider default.
apiKey String A key to test with instead of the stored one. Never stored, never echoed.
params JSON Edited params to test instead of the saved ones (#1413): validated exactly as a save validates them, including the params.baseUrl refusal, against the effective provider — before anything outbound. Used for the call, never stored. Omitted = the saved params; null = the edit clears them (the provider defaults). On the wire the probe exercises the effective provider/model/endpoint/key and (hard-capped at 16, per #1378's original ceiling pending a cost ruling) maxTokens, like its one-word prompt; the other knobs go through the same mapping every run uses (#1417): temperature, OpenAI reasoningEffort, Anthropic effort and Anthropic thinking (sent as adaptive on Claude 4.6 and newer models; not sent to older ones, which reject adaptive) are sent, and maxTokens is an output ceiling (min of the config's and the probe's cap); unrecognised keys are accepted but not forwarded. A write, or an edit under test, is refused a value outside a provider's known range (Anthropic and Bedrock temperature at most 1); a saved row is not re-judged. knobs on the result reports what each one did.

AmendDecisionInput

Field Type Description
title String
urgency DecisionUrgency
tier DecisionTier
context String
blocks [DecisionRefInput!]
sources [DecisionRefInput!]
followUps [DecisionRefInput!]
parts [DecisionPartPatchInput!]
addParts [DecisionPartInput!]

AppDeliverySettingsInput

Atomic patch: omit to preserve, explicit null refuses. Empty patch returns the current authorized settings.

Field Type Description
batchWindowSeconds Int Shared ticker floor/window; existing floor, self-cadence and live-ticker limits apply.
busyDelaySeconds Int
stuckWindowSeconds Int
checkPeriodSeconds Int #2138: whole seconds, 60..86400.
failedChecksToOverdue Int #2138: whole number, 1..100.
darkAlarmWindowSeconds Int #2755: whole seconds, 300..86400.

AppFilter

Filter for the uniform apps() list (#473). Clauses AND-combine.

Field Type Description
ownedByMe Boolean #782 — true restricts the list to the caller's OWN user-owned (org-less) apps: organizationId IS NULL AND ownerUserId = the caller. For ALL callers INCLUDING platform ADMIN/OWNER (owner scope is never an admin-bypass surface), mirroring the owner-only personal/private memories slice. Org-less by definition, so orgId is not consulted. App-key callers (no user context) get an empty page. Powers the portal's "My apps".
agentId ID #2343 — restricts the list to Apps that install this Agent (the AppAgent join; an App has no separate primary-agent column to match). Accepts an ID or a fully-qualified URN. The Agent must be one the caller can read: an unreadable, deleted, unresolvable or nonexistent Agent yields an empty page, never a not-found or forbidden error. Combines with ownedByMe and orgId.

AppTickerSettingsInput

Field Type Description
minCadenceSeconds Int
selfSubscribeCadenceSeconds Int
liveCap Int
wakeDailyBudget Int
clearWakeDailyBudget Boolean Return to the derived budget.

AskDecisionInput

Field Type Description
title String!
urgency DecisionUrgency
tier DecisionTier Default APPROVED; SIGNED when authorizes is true (APPROVED is then refused: DECISION_TIER_TOO_LOW).
authorizes Boolean
grant JSON The authorization a grant decision carries (authorizes: true only).
deciders [ID!] Narrows the log's default deciders; never widens past its eligible set.
context String
blocks [DecisionRefInput!]
sources [DecisionRefInput!]
followUps [DecisionRefInput!]
parts [DecisionPartInput!]!

AssetFilter

Filter for the cross-memory assets() list. Every field narrows the caller's accessible set; none of them widens it.

Field Type Description
memoryRefs [ID!] Narrow to these memories (id or fully-qualified URN). Unreadable and unknown refs are silently dropped; a malformed URN is an error. An explicitly EMPTY list is the empty scope, never a fallback to the default scope.
mine Boolean Only the caller's own uploads. Never widens the gate.
mimeType String
scanStatus AssetScanStatus
includeDeleted Boolean

AssignHostWorkerInput

Field Type Description
appRef String!
hostId String! The host's id within the App: the one its key's host:operate scope names. It need not have registered yet.
worker String! The worker: its id, URN or name within the App.
workdir String! The name the host knows the working directory by: a name token (letters, digits and . _ / @ + -, starting with a letter or digit, no .., // or trailing /), at most 256 characters.
family String! The model family it runs as there: one a host has a launcher for (claude, codex, glm or kimi).
model String The model, a profile token: letters, digits, . _ or -, starting with a letter or digit, at most 128 characters. Optional.
effort String #4230 — the effort, a profile token. Optional.
accountProfile String #4230 — the host-local account profile the launcher runs under, a profile token. Optional.
replace Boolean Change an existing assignment of this worker to this host instead of refusing HOST_ASSIGNMENT_EXISTS.

AuthoredWithInput

1328 — an authoring attestation. The writer states which task it worked from

and that task's current revision (Node.revSeq). The server compares both with the rule and refuses a mismatch: AUTHORING_ATTESTATION_MISSING, AUTHORING_ATTESTATION_WRONG_TASK, AUTHORING_ATTESTATION_STALE, or AUTHOR_TASK_BROKEN when the rule's task is gone, unusable or unreadable to the writer, whatever the claim. A match records a TASK stamp. This does not prove the task was read or followed. With no applicable rule the claim is ignored. People in the portal are exempt, derived from their sign-in; no client field selects that.

1329 — each refusal carries extensions taskAccess, task, taskId, taskRevision

and load. READABLE gives the task's URN (null when it has none that resolves), id, current revision and the node read per surface. UNAVAILABLE gives nulls and is the same for an unreadable task and a missing one: an owner must fix access or the rule.

Field Type Description
task ID! The task's id or canonical URN.
revision Int! The task's current revision.

AuthorizeContextResetStopInput

Field Type Description
appRef String!
resetId ID!
epoch Int!
process ObservedProcessInput! The agent process about to be stopped: the one the claim observed.

BatchThrough

Field Type Description
channelId ID!
seq Int! A seq this batch rendered in that channel.

BeginAssetUploadInput

Field Type Description
agentUrn String! Accepts the entity's ID or URN.
filename String!
mimeType String!
sizeBytes Int!
description String
uploadIntent UploadIntent!
uploadRequestId String

BeginAssetUploadV2Input

v2 (spec 006-asset-upload-redesign): memory-addressed input. memoryId is required for the attached upload path. The staging path (memoryId omitted) is added in US4.

Field Type Description
memoryId ID! Memory reference. Accepts the entity's ID (CUID / 32-char hex) or its URN (per spec 007 ID-or-URN dispatch). URN inputs MUST be fully qualified (org:memory) per spec 022 — relative-form URNs are rejected as GraphQL errors with extensions.code "URN_NOT_QUALIFIED".
filename String!
mimeType String!
sizeBytes Int!
description String
uploadIntent UploadIntent!
uploadRequestId String

CalendarEventTimeInput

An event boundary for create/update: exactly one of dateTime (timed) or date (YYYY-MM-DD, all-day). A dateTime needs timeZone unless it carries its own UTC offset — a zone-less value is rejected by the calendar tool (validation_error), never guessed.

Field Type Description
dateTime String
date String
timeZone String

ChannelFilter

Filter for channels(): by App (its host memories' Channels) or by one host memory. Refs: ID or URN.

Field Type Description
appRef ID
memoryRef ID

ClaimContextResetInput

Field Type Description
appRef String!
resetId ID!
epoch Int! The epoch the reset was collected at: 0.
process ObservedProcessInput! The agent process the host observed idle, which a later stop must still match.

CloneAgentTaskInput

2646: the overrides of a clone. Every field is optional; a field left out keeps the source's value (a copied field)

or stays unset (a field a clone does not copy). An optional field is cleared by naming it empty.

Field Type Description
title String
description String
source String
tags [String!]
references [AgentTaskReferenceInput!]
closeSessionWhenDone Boolean
priority Int A priority you name and may not set is refused, as on a create; a copied one you may not set is left out.
properties JSON
requirements AgentTaskRequirementsInput
parentTaskId ID Another parent in the same App, or null for none (a root under AT0, or a project with project: true).
project Boolean
owner AgentTaskPartyInput
assignee AgentTaskPartyInput
status AgentTaskCreateStatus
startBy DateTime
finishBy DateTime

CompleteAssetUploadInput

Field Type Description
uploadId ID!

ContextResetCheckpointInput

Field Type Description
title String! Nonblank after trim; at most 200 Unicode characters (CHECKPOINT_TITLE_MAX_CHARS); stored verbatim.
content String! At most 65536 UTF-8 bytes (CHECKPOINT_CONTENT_MAX_BYTES); bounds refused RECOVERY_REF_INVALID after reset admission.

ContextResetStepInput

2162 — a context reset step: the reset and the epoch the host holds (0 until claimed).

Field Type Description
appRef String!
resetId ID!
epoch Int!
lateStopMs Int #3255 (hrn:node:hadronmemory.com:specs:cor:agt:050:27 part 10): milliseconds the host's stop signal landed after its window, an integer from 0 to 86400000. Omitted, null or zero means no late-stop event. On the first stopped report, a positive value records one task.context-reset-late-stop event per reset for the worker's coordinator. Later reports record nothing, even if the first report had no annotation. After the reset ended, the same collected host may annotate its granted stop using that grant's epoch; this changes no reset, task, availability, outcome or alarm state. Other steps keep their epoch checks.

CreateAgentScheduleInput

Field Type Description
budgetTokens Int Optional per-run token limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
budgetActions Int Optional per-run action limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
appRef String! App the run executes as — ref: PK or fully-qualified URN.
name String!
cron String Recurring: 5-field cron expression, evaluated in timezone (default UTC). Provide exactly one of cron / runAt.
runAt String One-shot: run once at this ISO-8601 instant (#510). Provide exactly one of cron / runAt.
timezone String
entryNodeUrn String! Fully-qualified URN of the prompt node to run (D-2026-05-09-012/017).
agentRef String Agent — ref: PK or URN; must be installed in the App.
runAsSelf Boolean true: the run acts on behalf of YOU (required to reach your personal memories). v1 never delegates a third party (cor:agt:010:01).
eventData JSON Static payload merged into each run's template args.
policy JSON Trigger-layer allow-list { allow: [...] } — one link of the conjunctive chain (cor:acl:040).
aiConfigName String Named AI config for this trigger (spec-036 walk override).
enabled Boolean
scopeRef ID Spec 049 (D-2026-09-13-004): the scope this trigger's runs carry — a scope id, or a name resolved in the App's context (App › Agent › organization). Must be readable by you and resolvable in that App. Snapshotted onto each run at mint; omitted ⇒ the App's attached memories ('app').

CreateAgentTaskInput

createAgentTask input. A ROOT task names appRef; any App participant may create one (hrn:node:hadronmemory.com:specs:cor:agt:050:06). A CHILD task names parentTaskId; only the parent's assignee may create one, and it owns it (hrn:node:hadronmemory.com:specs:cor:agt:050:07).

Field Type Description
match Boolean Run one blocking match. Failure is marked and skipped by automatic runs. Assignment, cancellation, or park then ready clears it. Only for pending, unblocked tasks without an assignee; a blocked create refuses BAD_USER_INPUT atomically. Batch items run requested attempts in list order after the whole commit; a blocked match item refuses the whole call before commit, with its position. No distinct-workers guarantee.
priority Int #2644 — naming priority or blockers requires the task assigner authority; otherwise creation refuses atomically.
blockedBy [ID!]
appRef ID The team App (id or URN). Required for a root task; for a child task it is taken from the parent and, if given, must match.
parentTaskId ID
project Boolean Make a top-level PROJECT (AT1, AT2, ...) instead of a task under the reserved project AT0. Not with parentTaskId.
title String!
description String
source String
externalId String #3125 S2 (hrn:node:hadronmemory.com:specs:cor:agt:120:02): the outside item this task claims, for example an issue's canonical URL. Stored and compared exactly as written; 1 to 512 characters with no whitespace, control or invisible format character and no user name or password (else BAD_USER_INPUT). Set only here: no edit takes it. A second task with the same value in this App, whatever the first task's state, is refused TASK_EXTERNAL_ID_TAKEN, which names no task (find it with agentTasks(externalId:)). Another App's tasks never conflict. #4113 (hrn:node:hadronmemory.com:specs:cor:agt:050:02): naming it with YOURSELF as the assignee is the claim, and a claim is created STARTED in this one call (startedAt set; task.created, task.assigned, task.started; never queued, matched or alarmed as not started). A claim naming another assignee, no assignee, or an open blocker stays PENDING (hrn:node:hadronmemory.com:specs:cor:agt:050:08 governs the first); a backlog task still takes no assignee.
owner AgentTaskPartyInput Defaults to the creator. A root task's creator may name any other participating worker or person as owner (#1757, hrn:node:hadronmemory.com:specs:cor:agt:050:01); a ref outside the App's participants is TASK_OWNER_INVALID. Never for a child task, whose owner is its parent's assignee (TASK_CHILD_OWNER_MISMATCH).
assignee AgentTaskPartyInput Omit to leave the task queued.
requirements AgentTaskRequirementsInput
runSettings AgentTaskRunSettingsInput #4291 (hrn:node:hadronmemory.com:specs:cor:agt:050:01): the task's own run settings, each optional. What a start for this task launches, before the worker's last used; never a matching requirement. Checked here, at creation, and refused TASK_RUN_SETTINGS_INVALID with a reason. Set only here: no edit takes them, and a clone copies none.
properties JSON #2420 (hrn:node:hadronmemory.com:specs:cor:agt:050:28): the task's own properties, a JSON object with the same limits and refusal codes as on update. Only set when the creator is one of the task's writers (its owner, someone above the owner, a manager, or the assignee named here); any other creator gets the task made without them, not a refusal.
startBy DateTime
finishBy DateTime #2648 (hrn:node:hadronmemory.com:specs:cor:agt:050:14): an optional finish-by deadline; refused BAD_USER_INPUT if in the past or earlier than startBy. While set, the task raises no stall-window alarm, only stall.finish-by once it passes unfinished.
tags [String!]
references [AgentTaskReferenceInput!] #2649 (hrn:node:hadronmemory.com:specs:cor:agt:050:01): the task's ordered references; any creator may set them, as it sets the title.
closeSessionWhenDone Boolean Defaults to false: the assignee's session ends only when whoever assigns the task asks (hrn:node:hadronmemory.com:specs:cor:agt:050:10).
status AgentTaskCreateStatus #1754 — PENDING (the default) or BACKLOG (hrn:node:hadronmemory.com:specs:cor:agt:050:02). A BACKLOG task is parked: it takes no assignee (BAD_USER_INPUT), never enters the queue, and is moved to pending by assigning it or making it ready.

CreateAgentTasksItemInput

2653 (hrn:node:hadronmemory.com:specs:cor:agt:050:06): one task of a createAgentTasks call.

Field Type Description
task CreateAgentTaskInput! The task, exactly as createAgentTask takes it. appRef may be left out; if given it must be the call's App.
blockedByPositions [Int!] Other tasks of the same call that block this one, by their 1-based position in the list.

CreateAgentWebhookInput

Field Type Description
budgetTokens Int Optional per-run token limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
budgetActions Int Optional per-run action limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
appRef String! App — ref: PK or fully-qualified URN.
name String! Lowercase alphanumeric/dash, 1-64 chars — part of the URL.
entryNodeUrn String!
agentRef String Agent — ref: PK or URN; must be installed in the App.
runAsSelf Boolean
argsSchema JSON JSON Schema for POST args (stored in v1; enforcement is follow-on).
eventData JSON
policy JSON
aiConfigName String
enabled Boolean
scopeRef ID Spec 049 (D-2026-09-13-004): the scope this webhook's runs carry — a scope id, or a name resolved in the App's context. Snapshotted onto each run at mint; omitted ⇒ 'app'.

CreateAssetReferenceNodeInput

Attach an existing asset to the graph by creating a reference node that points at it.

The node is a nodeType: reference node whose data.asset carries the asset's id, urn, filename, mimeType and sizeBytes — the same shape hadron_store_file writes for run-created files, so a reader handles both origins identically. There is no schema-level Asset-to-Node link (cor:dmo:060:10 reserves it); the pointer is a soft reference, and Node.asset resolves to null once the asset is gone.

Requires READ access to the asset's holding memory and WRITE access to the memory the reference node lands in — which need not be the same memory.

Field Type Description
assetRef String! Asset id, or its URN — canonically hrn:asset:<root>:<mem...>:assets:<asset.id>. Parsing is Postel-liberal (assetIdFromRef): the id is whatever follows the LAST 'assets' atom, so every shape Asset.urn can emit is accepted, including the pre-#697 memory-prefixed <memory.urn>:assets:<asset.id> spelling and the other degraded fallback. A ref with no 'assets' atom is taken as a bare id.
nodeUrn String! Fully-qualified node URN for the reference node.
name String Node name. Defaults to the asset's filename.
description String Node description. Defaults to the asset's own description.

CreateChannelInput

Create a named Channel WITH its chat root, in one transaction. The host may be a memory of ANY class that you may write — the host memory's own audience decides who reads and posts (cor:acl:030:01), so a Channel in a private memory is private and one in an app memory is the App's. loc is the reserved address (e.g. chats:release) and must not overlap an existing Channel's; chats:team is every App's default and is created with the App.

There is no app-class precondition. This said there was until #1248 — the rule was retired by #1196 and the description outlived it, so every client mirroring this SDL published a refusal that cannot fire.

Creating at a DELETED Channel's address starts CLEAN (#1226). The address stays reserved by the tombstone, so a create here adopts it rather than inserting beside it — and the previous Channel's messages are tombstoned so the new room is empty. The allocator history remains, while the empty Channel's last-sequence and last-message watermarks reset. Its first new message therefore resumes above the old maximum, so an old read cursor cannot hide it. Expect a gap in the numbering, never inherited transcript or phantom attention.

Field Type Description
memoryRef ID!
loc String!
name String!
description String

CreateGrantInput

3690 PR 2 (hrn:node:hadronmemory.com:specs:cor:acl:140:05): what a bound worker asks for. There is deliberately no field for activation, a verifier, a signature, a use count, a version or an issuer: a grant is born pending and only signing (#3649) can make it live.

Field Type Description
appRef String #3711: the App a PERSON who manages it creates the grant in (id or URN). A bound worker session omits it: the worker's own App is used and a value naming another is refused. Whoever manages an App creates for a worker of it, or an agent installed in it; the row is still born pending.
action String! A registered action's dotted name, such as schedule.create.
values JSON! Exactly the action's declared parameters, each a string or a list of at most 100 distinct strings per parameter (an id, never a URN; hrn:node:hadronmemory.com:specs:cor:acl:140:01). Any other key or shape is refused. Never put a secret here.
holderKind GrantHolderKind! WORKER (the calling worker itself) or AGENT (its role agent, installed in this App). Any other holder is refused.
holderRef String! The holder's id (not a URN).
startsAt DateTime The grant is not usable before this time once it is signed.
expiresAt DateTime Not usable after this time; must follow startsAt when both are given.
maxUses Int At most this many uses once signed; a positive integer.
reason String! Why the grant is asked for: at most 2,000 Unicode characters (code points; hrn:node:hadronmemory.com:specs:cor:acl:140:01). Shown to the signer as the requester's words, labelled as theirs.

CreateMemoryConfigTemplateInput

1325 part (c) — a new template. rules are validated as a whole before anything is written.

Field Type Description
name String!
description String
required Boolean
orgDefault Boolean #3426 — an ORGANIZATION-owned template applied to every new org `knowledge` or `group` memory at its creation (`createMemory` only; never clone, extract, App, install, agent or chat creation). A starting configuration, not a boundary. User-, App- and server-owned templates refuse true (BAD_USER_INPUT, reason ORG_DEFAULT_ORG_ONLY). At most 10 live defaults per organization (ORG_DEFAULT_LIMIT). Setting it true validates every reference as readable to the ORGANIZATION as well as the saver (NODE_NOT_FOUND otherwise); clearing it never validates. Proposed addition built on the #3426 gate to hrn:node:hadronmemory.com:specs:cor:api:290.
rules [CreateNodeRoleRuleInput!] Each role at most once (NODE_ROLE_RULE_EXISTS).

CreateNodeInput

Input for createNode. 'loc' and 'name' are required, plus EITHER 'memoryId' or 'install' (an App's install memory, #2044) — both or neither is an error (BAD_USER_INPUT). Creating is create-only — a live node at (memoryId, loc) rejects with NodeLocConflictError (spec 039 Phase 0 D1/D4).

Field Type Description
authoredWith AuthoredWithInput #1328 — the author task this write worked from, required when the node's role rule names one (before and after the write). See AuthoredWithInput.
id String Forced PK (importer/sync use case, e.g. a stable UUIDv7). Only ever a create-id here — never a selector (D2). Omit to mint.
memoryId String Memory reference. Accepts the entity's ID (CUID / 32-char hex) or its URN (per spec 007 ID-or-URN dispatch). URN inputs MUST be fully qualified (hrn:mem:<root>:<memory>) per spec 022 — relative-form URNs are rejected as GraphQL errors with extensions.code "URN_NOT_QUALIFIED".
install InstallTargetInput #2044 — an App's install memory as the target, instead of 'memoryId'. See InstallTargetInput.
loc String!
name String!
nodeType String
objectType String #725 — collection discriminator (e.g. "competitor" / "insight"). NULL for an ordinary node.
isRunnable Boolean Whether this node can be run as a task by hadron_run_task (cor:api:060).
role String #1201 — what this node is FOR (open string). NOT 'nodeType' (the platform-kind axis) and NOT 'objectType' (the collection discriminator). A GOVERNED family ('review', 'spec', 'decision', including dotted descendants) requires that kind's own door; generic createNode refuses it.
alias String
description String
abstract String Paragraph-length summary of this node — see Node.abstract for the surfacing contract. Optional. Empty + whitespace-only normalize to null. Cap is 2000 characters.
content String
contentType String MIME type of content (#476/#488, spec cor:cnv:010:01): 'text/markdown' (default) stores as-is; 'text/html' converts captured DOM to Markdown; 'application/pdf' extracts a PDF's text layer to Markdown (send 'content' as raw base64 — a PDF is binary; scanned/image-only PDFs error). The conversion runs before storage and fills properties.title from the extracted title when not supplied. Consumed at write time — never persisted. Any other value is rejected.
seq Int
tags [String!]
properties JSON
data JSON
ownerRepo String
llmModel String
aiAgent String
edges [NodeEdgeInput!] Outgoing edges to create with the node.
reason String Recorded on revision history only when a soft-deleted node is resurrected (a pure create snapshots nothing).

CreateNodeRoleRuleInput

1325 — a new rule, in a memory's config or in a template's rule list.

Task and description references are node IDs or URNs you can read; a node you cannot read is refused exactly like a missing one (NODE_NOT_FOUND), and a task reference must be a runnable task (NOT_A_TASK).

Field Type Description
role String! Lower-case letter/digit/dash segments joined by dots, 1-64 characters (INVALID_NODE_ROLE).
authorTaskRef ID
validationTaskRef ID
descriptionNodeRef ID
strictSubRoles Boolean
writers NodeRoleWriters
validateBy ContentValidator Needs a validation task.
enabled Boolean

CreateRegisterEntryInput

Field Type Description
ownerRef ID! An App or an organization (URN or id).
channelRef ID! A Channel: its id or its address (Channel.chatRootUrn, #1171).
attendeeRef ID A Worker or an Agent in the owner's context; omitted = every attendee there.
role RegisterRole Default BOTH.
mentionOnly Boolean
description String

CreateScopeInput

Exactly one of organizationRef / agentRef / appRef. memoryRefs is the ORDERED list (IDs or URNs); each must be readable by you — an unreadable memory reads as "no match", the same as a nonexistent one.

Field Type Description
name String!
description String
organizationRef ID
agentRef ID
appRef ID
memoryRefs [ID!]!

DashboardWidgetInput

One widget in a setDashboardWidgets selection; grid position is the array order.

Field Type Description
id ID When set and owned by the caller, update that placement in place (id survives the save); otherwise create a new one (#788).
type DashboardWidgetType!
span Int! Columns to span (1-12) on the 12-col grid; clamped server-side.
rowSpan Int! Rows to span (1-4); clamped server-side (#788).
config JSON Widget-instance settings; shape is widget-defined (#788).

DecisionNoRecommendationInput

Field Type Description
reason String!

DecisionOptionInput

Field Type Description
key String!
label String!
meaning String
cost String

DecisionPartInput

1641 — one part of a decision. Give options or yesno, and a recommendation or noRecommendation.

Field Type Description
question String!
options [DecisionOptionInput!]
yesno Boolean
recommendation DecisionRecommendationInput
noRecommendation DecisionNoRecommendationInput

DecisionPartPatchInput

1641 — a change to an existing part (by its permanent number). Omitted fields are unchanged; answers never change here.

Field Type Description
n Int!
question String
options [DecisionOptionInput!]
yesno Boolean
recommendation DecisionRecommendationInput
noRecommendation DecisionNoRecommendationInput

DecisionRecommendationInput

Field Type Description
key String!
reason String
attributedTo String Relaying someone else's recommendation: who (recorded as a claim).

DecisionRefInput

Field Type Description
ref String
node String
spec String

EdgeFilter

Filter for the uniform edges() list (#473). Clauses AND-combine and are intersected with the caller's readable memories. memoryId / sourceNodeId / targetNodeId each accept an ID or a fully-qualified URN; an unresolvable ref yields an empty page (consistent with the no-disclosure posture).

Field Type Description
memoryId ID Confine to edges whose (denormalized, source-side) memory is this one.
sourceNodeId ID Edges leaving this node.
targetNodeId ID Edges arriving at this node.
isRunnable Boolean #2999 — runnability is tri-state, with parity to the node filter. true returns only runnable edges; false returns only edges explicitly marked not runnable. An edge never marked (NULL) matches neither, and only an omitted filter returns it. (hrn:node:hadronmemory.com:specs:cor:dmo:060:03)
includeDeleted Boolean Include soft-deleted edges (default false).

EdgeInput

Field Type Description
sourceLoc String!
targetLoc String!
name String Relationship name (was 'label'). Optional — loc is the identity.
loc String Explicit edge loc. Omit to derive <sourceLoc>:<name>:<targetLoc>.
description String
isRunnable Boolean

EndAgentlessSessionInput

Field Type Description
appRef String!
workerRef String! The worker: its id, URN or name within the App.
sessionId ID! The worker's open session to end.
reason AgentlessEndReason!

GrantCreditsInput

Field Type Description
orgRef String!
amountMicroCents String! Positive micro-cents, base-10 integer string.
expiresAt String Grant expiry policy field (no enforcement in Phase 0).
sourceType String Idempotency + provenance pair (both or neither), e.g. ('stripe-checkout', <session id>). (sourceType, sourceId) is unique across the ledger - re-granting the same pair returns the EXISTING entry instead of double-crediting (at-least-once webhook safety).
sourceId String
note String

HostSweepRunLineInput

Field Type Description
worker String!
outcome SweepRunOutcome!
reason String!

ImpersonationSessionFilter

Field Type Description
activeOnly Boolean Only sessions that are live right now (endedAt null, unexpired).

ImportNodeInput

Input for importNode (#457). Target: 'nodeUrn' XOR ('memoryId' + 'loc') — the URN may name a not-yet-existing node (import creates it). Source: exactly one of 'url' | 'content'.

Field Type Description
authoredWith AuthoredWithInput #1328 — the author task this write worked from, required when the node's role rule names one (before and after the write). See AuthoredWithInput.
memoryId String Target memory (ID or fully-qualified URN), with 'loc'. XOR with 'nodeUrn'.
loc String Target loc within 'memoryId'. XOR with 'nodeUrn'.
nodeUrn String Fully-qualified node URN naming the target (existing or new). XOR with memoryId+loc.
url String Source URL (http/https) — fetched server-side, SSRF-guarded, WITHOUT user credentials.
content String Inline source content (e.g. the Web Clipper's authenticated-DOM capture). XOR with 'url'.
contentType String MIME type of 'content': text/html (DEFAULT here — unlike createNode) converts to Markdown at the write seam; text/markdown stores as-is; application/pdf extracts a PDF's text layer to Markdown ('content' must be raw base64 — a PDF is binary; scanned/image-only PDFs error). Ignored on the url path (always HTML).
name String Display name. Default: the extracted page/article/document title; on a re-import of an existing node the current name is preserved; a fresh create without either falls back to the loc leaf.
nodeType String Default 'webpage' (or 'info' when contentType is application/pdf).
properties JSON Merged provenance metadata; the server sets properties.url on the url path when absent (properties.title is filled from the extracted title by the write seam).
taskRef ID Task node to run against the imported node once stored (#528) — PK or fully-qualified URN. Presence triggers a MANUAL app run; the result envelope is FETCH_PENDING + jobId (poll appRun(ref:)). The imported node's URN is passed to the task as eventData.importedNodeUrn.
taskArgs JSON Extra template args merged into the task run's eventData (only meaningful with taskRef).
appRef ID App to run the task under — PK or URN. Falls back to the caller's active App. Only meaningful with taskRef.
agentRef ID The Agent the task run is served as (PK or URN), installed in the App. Omit to use the App's single installed Agent; an App with several refuses with RUN_AGENT_REQUIRED before anything is written (#2735). Only meaningful with taskRef.

InstallTargetInput

2044 (hrn:node:hadronmemory.com:specs:cor:agt:040:06) — names an App's INSTALL MEMORY by the pair that

identifies it: the App and the Agent it customises. Both are ID-or-URN refs like every other entity ref (relative URNs are refused, URN_NOT_QUALIFIED). Accepted by createNode / updateNode in place of 'memoryId'. The install memory is created by the App's first customisation: a createNode through this target finds-or-creates it in the same transaction as the write, so a refused write leaves nothing behind. Only whoever manages the App may write through it, and only while the App is live and the Agent installed. After the App participant and manager gates, both createNode(input.install) and updateNode(input.install) refuse an Agent held only through an import without the App organisation's active grant with AGENT_ORG_GRANT_REQUIRED, and an absent Agent with AGENT_NOT_INSTALLED. These refusals write nothing; physical install rows keep their existing behavior (hrn:node:hadronmemory.com:specs:cor:agt:040:15). updateNode never creates an install memory: an installed, licensed Agent with no customisation memory answers INSTALL_MEMORY_NOT_FOUND. A detached retained memory does not make an Agent installed.

Field Type Description
appRef String!
agentRef String!

IssueHostOperationInput

Field Type Description
appRef String!
hostId String! The registered host to run it.
worker String! The worker it is for: its id, URN or name within the App.
type String! One of the closed set; see HostOperation.
args JSON The type's arguments, without workerId (taken from worker).

MemoryConfigTemplateFilter

Filter for memoryConfigTemplates(). Narrows the templates you manage; it never widens them.

Field Type Description
ownerType MemoryConfigTemplateOwnerType
ownerRef ID ID or URN of the owner (with ownerType). An owner you do not manage matches nothing.

MemoryFilter

Filter for the uniform memories() list (#473). All clauses AND-combine and only ever narrow the caller's accessible scope — with two documented slice SELECTIONS, each switching which readable set the list draws from (never widening access beyond what the caller may already read): - visibility: PUBLIC switches from the caller's own union (org-owned + org-subscribed + own user-owned) to the public marketplace slice (every PUBLIC memory — the old publicMemories query). - sharedWithMe: true switches to the memories shared WITH the caller via MemoryShare (the caller is a grantee) — the portal's Memories-shared-with-me tab.

Field Type Description
memoryClasses [MemoryClass!] Restrict to exactly these classes. Omitted, the noisy agent system class is hidden by default; pass it explicitly to surface system memories.
visibility MemoryVisibility Restrict by visibility. PUBLIC selects the marketplace slice (see above).
sharedWithMe Boolean true selects the distinct set of memories shared WITH the caller via MemoryShare (the caller is a grantee) — the portal's Memories-shared-with-me tab. This is its own slice, NOT part of the caller's owned/org union: a grantee is never their own grantor, so it excludes owned memories. App-key callers get an empty page (sharing is a user-to-user concept). See Memory.myShare for the per-row grantor + role.
ownedByMe Boolean #1179 — true restricts the list to the caller's OWN ORG-LESS memories: organizationId IS NULL AND the caller owns it. For ALL callers INCLUDING platform ADMIN/OWNER (owner scope is never an admin-bypass surface), the same intent as AgentFilter.ownedByMe and AppFilter.ownedByMe. Org-less by definition, so orgId is not consulted. App-key callers (no user context) and impersonated sessions get an empty page. Powers the portal's "My memories". "Owns it" is PER CLASS, because Memory has two independent owner columns and the read gates already split on exactly this line (canReadMemoryRecord and the MCP canReadMemory both branch on personal/private FIRST and admit userId there, falling through to ownerUserId for every other class): - personal / private → userId, the STRICT owner; - every other class → ownerUserId, the spec-047 user TENANT owner. This is where the memory filter is NECESSARILY wider than its Agent and App siblings, which have one owner column each and can say ownerUserId alone. Keying memories on ownerUserId alone would hand a personal memory to its tenant owner when the two columns differ — legal rows, since nothing constrains them to agree — while memory(ref:) refuses that same caller. Keying on the class pair alone was the ORIGINAL defect: it was only ever a proxy for ownership, correct while the two coincided (#1176). So a knowledge-class memory under a user root (hrn:mem:holger:holgers-gear) is in this slice, and an ORG-owned personal memory is not (it has an organizationId) — which matches what the portal's class-plus-client-side-repair query already returned. Composes by AND like every other clause, so it only ever narrows: combined with visibility PUBLIC it is empty by construction (#758 excludes user-owned rows from the marketplace slice), and combined with sharedWithMe it narrows that slice rather than replacing it.

MergeMemoriesInput

Field Type Description
source String! Source memory — ID or fully-qualified URN. Emptied into 'target'.
target String! Target memory — ID or fully-qualified URN. The surviving memory.
include [NodeMergeField!] Field strategy for source nodes whose loc collides with an existing target node (folded via the mergeNodes rules). Omit (or null) = every mergeable field. Nodes with no target counterpart move over unchanged (loc preserved).
deleteSourceMem Boolean Delete the (now-empty) source memory after a successful merge.

MergeNodesInput

Field Type Description
authoredWith AuthoredWithInput #1328 — the author task this write worked from, required when the node's role rule names one (before and after the write). See AuthoredWithInput.
source String! Source node — ID or fully-qualified URN. Folded into 'target'.
target String! Target node — ID or fully-qualified URN. The surviving node.
include [NodeMergeField!] Fields to merge. Omit (or null) to merge every mergeable field.
deleteSource Boolean Hard-delete the source node after a successful merge.

MergeUsersInput

Field Type Description
consentProof String Single-use dual-login proof from beginMergeUsersConsent, approved by both accounts. Required at execution; absent refuses MERGE_CONSENT_REQUIRED.
source String! Source user — ID, bare handle, or fully-qualified user URN. Folded into 'target' and soft-deleted.
target String! Target user — ID, bare handle, or fully-qualified user URN. The surviving user; target wins non-combinable conflicts while roles preserve the strongest live entitlement.

MintActionTicketsInput

Field Type Description
orgRef String! Organization — ref: PK or URN.
appRef String Scope tickets to one App (ref: PK or URN); omit for org-wide.
action String! v1: comm.outbound only.
count Int!
note String Ledger legibility — why these tickets exist.
expiresAt String

NodeEdgeInput

Outgoing edge on a node, used in NodeInput.edges

Field Type Description
targetId String! Reference to the target node. Accepts a node ID, a full URN (hrn:node:<memory-urn>:<loc>), a memory-prefixed loc (<memory-urn>:<loc>), or a short loc resolved within the source node's memory.
name String Relationship name (was 'label'). Optional — loc is the identity.
loc String Explicit edge loc. Omit to derive <sourceLoc>:<name>:<targetLoc>.
description String
isRunnable Boolean

NodeFilter

Structured, unscored, AND-combined filter context for findNodes (cor:api:090:02).

Field Type Description
memoryIds [ID!] Memory scope — a mix of memory IDs and fully-qualified URNs; intersected with the caller's access.
memoryClasses [MemoryClass!] Restrict by memory class. SYSTEM is excluded by default; passing this (or naming a system memory in memoryIds) overrides that.
nodeType String Without it, system and chat-message nodes are left out (hrn:node:hadronmemory.com:specs:cor:api:090:02); naming one of them returns it. record nodes are never left out. An explicit 'comment' with no contentScope searches comments (as COMMENTS).
nodeTypes [String!] #3113 — an explicit list of node types, a union: only nodes whose type is in the list (hrn:node:hadronmemory.com:specs:cor:api:090:02). It narrows, ANDs every other filter and, being explicit, replaces the default that leaves out system and chat-message nodes; it never lifts the memory-class default, access, deleted rows or inheritance. Values are exact and case-sensitive; an unknown value matches nothing. null is the same as omitted. Refused with BAD_USER_INPUT: an empty list, both nodeType and nodeTypes (an empty string counts as set), more than 20 entries (counted before duplicates are dropped), and a list containing "comment" (search comments with nodeType or contentScope). Exact total where the mode already has one; vector and hybrid keep total null and their bounded, widening candidate window. Applies to findNodes and appNodes.
contentScope NodeContentScope #1608 — content, comments or both (hrn:node:hadronmemory.com:specs:cor:dmo:110:08). Default CONTENT. Applied by the server before ranking, pagination and limits in every mode (keyword, regex, vector, hybrid and filter-only), so a COMMENTS search finds every matching comment the caller may read.
objectType String #725 — collection facet: only nodes whose objectType equals this (e.g. "competitor").
tags [String!]
isRunnable Boolean #2999 — runnability is tri-state. true returns only runnable rows; false returns only rows explicitly marked not runnable. A row never marked (NULL) matches neither, and only an omitted filter returns it. (hrn:node:hadronmemory.com:specs:cor:api:060:04)
hasOpenThreads Boolean #3494 — true selects nodes with a live OPEN top-level comment; false selects nodes with none. Deleted roots and deleted-with-replies stubs never count (hrn:node:hadronmemory.com:specs:cor:dmo:110:05 / hrn:node:hadronmemory.com:specs:cor:dmo:110:10). Null or omitted leaves results unchanged. AND-combined before ranking, counts and paging in every findNodes mode; it grants no access. Inherited projections have a zero summary: true excludes them, false includes them. Concealed install-write responses are not search projections. Unscored expansion context adds only this thread check to its existing memory/deletion/content-scope checks; other filters keep their candidate-only behavior there. Counts exclude appended context. appNodes/appNodesPage refuse either boolean with BAD_USER_INPUT. Proposed addition built on the #3494 gate to hrn:node:hadronmemory.com:specs:cor:api:090:02; comment result scope stays hrn:node:hadronmemory.com:specs:cor:dmo:110:08.
role String #1322 — role-family filter. 'spec' matches 'spec' and 'spec.*' on a dot boundary, never 'special' / 'specification'.
locPrefix String
childrenOf String #2832 — direct children only (hrn:node:hadronmemory.com:specs:cor:api:090:02). Matches the nodes whose loc is exactly the given loc plus one more segment (no further colon); the empty string means the top-level nodes. Judged on loc strings alone: edges and parentRel play no part, and a loc whose parent has no node of its own is still listed. An absent or null value is no filter, so the empty string is a value. Applies in every mode (keyword, regex, vector, hybrid and filter-only), under the same access and default exclusions as the rest of the filter, and pages and counts like any findNodes read. With no query and no sort the order is the sibling order of hrn:node:hadronmemory.com:specs:cor:dmo:020:01 (positioned nodes first, then by loc). Not supported by appNodes.
createdBy String
updatedAfter String
updatedBefore String
includeDeleted Boolean Include soft-deleted nodes (default false).
where NodeWhereInput Structured predicate over the node's properties/data JSONB (#719). Not supported by appNodes (refused with BAD_USER_INPUT); use findNodes (#3427).
approvalState NodeApprovalState #1591 — only nodes in this approval state (read from the stored revision; a node changed outside a revisioned writer is reconciled on its next read).
minted Boolean #1591 — only minted (true) or unminted (false) nodes.

NodeInput

Legacy bulk-import node shape retained for replaceSubtree compatibility. replaceSubtree now refuses without writing; single-node writes use CreateNodeInput / UpdateNodeInput (spec 039 Phase 0 D1).

Field Type Description
id String Forced PK (importer-supplied UUIDv7 from node.yaml, stable across moves). Omit to mint.
memoryId String! Memory reference. Accepts the entity's ID (CUID / 32-char hex) or its URN (per spec 007 ID-or-URN dispatch). URN inputs MUST be fully qualified (hrn:mem:<root>:<memory>) per spec 022 — relative-form URNs are rejected as GraphQL errors with extensions.code "URN_NOT_QUALIFIED".
nodeType String
objectType String #725 — collection discriminator (e.g. "competitor" / "insight"). NULL for an ordinary node.
isRunnable Boolean Whether this node can be run as a task by hadron_run_task (cor:api:060).
loc String!
name String!
alias String
description String
abstract String Paragraph-length summary of this node — see Node.abstract for the surfacing contract (hadron_get_node opt-in via contentScope; hadron_find_nodes preview ships in US2). Optional. Omit to preserve; null to clear; string to replace. Empty + whitespace-only normalize to null. Cap is 2000 characters.
content String
seq Int
tags [String!]
properties JSON
data JSON
ownerRepo String
llmModel String
aiAgent String
edges [NodeEdgeInput!] Replace all outgoing edges when provided (omit to leave edges unchanged)
reason String Why this change was made — recorded on the revision-history snapshot (NodeRevision.revLabel, #620; historically it squatted in editedBy), mirroring hadron_update_node's reason arg so CLI and MCP edits leave equally-traceable history. Only an update snapshots a prior revision, so reason has no effect on a pure create.

NodePropertySort

Order findNodes by the value at a properties/data JSON path (#719).

Reuses the NodeWhere leaf addressing: path into field (properties|data), typed by as (text|number|datetime|boolean). number/datetime route through the same DB guards, so a missing or unparseable value sorts LAST regardless of direction; loc ascending breaks ties for stable pagination. Overrides the sort enum when present. On vector/hybrid modes it re-orders the retrieved candidate window (the ranking runs against the vector index, not the JSONB), like the sort enum does.

Field Type Description
path [String!]! Path of object keys into the column, e.g. ['stage'].
field NodeWhereColumn JSONB column (default properties).
as NodeWhereCast Value typing before comparison (default text).
direction SortDirection Direction (default asc).

NodeWhereInput

A recursive structured predicate over a node's properties/data JSONB (#719).

A node is EITHER a branch (exactly one of and/or/not) OR a leaf (a path plus exactly one operator). Leaf values are JSON scalars, bound as parameters; path segments are identifier-validated. datetime/number comparisons route through DB guard functions so unparseable data drops the row (never a 500). Bounded: depth ≤ 4, ≤ 32 leaves, path ≤ 8 segments — a malformed/oversized tree is BAD_USER_INPUT. Composes with every mode (keyword/regex/vector/hybrid) and the no-query browse: for lexical modes + browse the predicate is applied in-query; for vector/hybrid it post-filters the ranked candidate set (rank order preserved).

Field Type Description
and [NodeWhereInput!]
or [NodeWhereInput!]
not NodeWhereInput
field NodeWhereColumn JSONB column (default properties).
path [String!] Path of object keys into the column, e.g. ['capturedAt'].
as NodeWhereCast Value typing for the comparison (default text).
eq JSON
ne JSON
in [JSON!]
lt JSON
lte JSON
gt JSON
gte JSON
between [JSON!]
exists Boolean
contains JSON jsonb containment (@>) of the JSON value at the path.

ObservedProcessInput

2162 — the agent process a host observed: its pid and the kernel's start time for it (a token).

Field Type Description
pid Int!
startTime String!

OrganizationFilter

Filter for the uniform organizations() list (#473).

Field Type Description
memberOnly Boolean true restricts the list to the caller's own memberships — even for platform ADMIN/OWNER, whose unscoped reach otherwise spans every live org; the old myOrganizations semantics.

PreviewAgentScheduleInput

3457: what a schedule would do, asked before it exists. The inputs create takes that the pin or the timing sentence depend on; the schedule's own name, policy and scope never do. Resolved exactly as createAgentSchedule resolves them.

Field Type Description
budgetTokens Int
budgetActions Int
appRef String! App the run would execute as - ref: PK or fully-qualified URN.
cron String Recurring: 5-field cron, evaluated in timezone (default UTC). Provide exactly one of cron / runAt.
runAt String One-shot: ISO-8601 instant. Provide exactly one of cron / runAt.
timezone String
entryNodeUrn String! Fully-qualified URN of the prompt node to run.
agentRef String Agent - ref: PK or URN; must be installed in the App.
runAsSelf Boolean
eventData JSON Static payload; only its __aiConfigName entry can change what is previewed.
aiConfigName String
enabled Boolean

PublicAgentFilter

Filter for the publicAgents() marketplace slice (#551). ONLY 'type' narrows. Deliberately a SEPARATE, narrower input from AgentFilter: the slice is PUBLIC by definition (so 'visibility' is meaningless) and a PUBLIC agent is never user-owned (user-owned agents are strictly PERSONAL, spec 047), so an 'ownedByMe' here would always be empty — rejecting it at the schema keeps a client from applying the filter uniformly and silently getting cross-org marketplace agents (#782 Codex review).

Field Type Description
type AgentType

RecordHostSweepRunInput

Field Type Description
appRef String!
runId String! A token of 1 to 64 letters, digits and . _ : - that names this run for this host; a replay is the same run.
startedAt DateTime!
endedAt DateTime! Not before startedAt, not more than two minutes ahead of the server, and within an hour of startedAt.
mode SweepMode! OBSERVE or APPLY.
planned Int!
applied Int!
skipped Int!
failed Int!
lines [HostSweepRunLineInput!] At most 50.

RegisterContextResetRecoveryInput

Field Type Description
appRef String!
resetId ID!
epoch Int!
checkpointNode String The checkpoint node the host wrote: its id or full URN, in the worker's own working memory.
checkpoint ContextResetCheckpointInput #3276: atomically write one plain checkpoint in the reset worker working memory; exactly one of checkpointNode/checkpoint.
sessionId ID! The reset's own session and task.
taskId ID The task the reset belongs to; omitted (or empty) for a reset with no task, one asked for by the Agent's context cap (cause context-cap).

RegisterDefaultsInput

Field Type Description
mentionOnly Boolean

RegisterEntryFilter

Filter for registerEntries(). Refs: ID or URN.

Field Type Description
ownerRef ID An App or an organization.
channelRef ID A Channel: its id or its address (Channel.chatRootUrn). A ref naming nothing matches nothing.
attendeeRef ID A Worker or an Agent.

RegisterHostInput

Field Type Description
appRef String!
label String!
pollIntervalSeconds Int! How often the host checks in; it lapses after the App's count of these without one.
workers [RegisterHostWorkerInput!] The whole list: it replaces the last registration's.
capabilities [String!] #2162 — the capability-gated operation types this host performs, in full at every refresh: worker.reset-context. Omitted means none. Anything else is BAD_HOST_REGISTRATION.

RegisterHostWorkerInput

Field Type Description
worker String! The worker: its id, URN or name within the App.
family String! The model family it would run as here, e.g. claude or codex.
worktrees [String!] Its existing worktrees on this host, as the host names them (at most 32 name tokens).

ReportContextResetRelaunchFailedInput

Field Type Description
appRef String!
resetId ID!
epoch Int!
reason String! CHECKPOINT_FAILED, STAGING_FAILED, RELAUNCH_UNVERIFIED or RELAUNCH_BLOCKED.

ReportContextResetRelaunchedInput

Field Type Description
appRef String!
resetId ID!
epoch Int!
process ObservedProcessInput! The relaunched agent process.

ReportHostOperationInput

Field Type Description
appRef String!
id ID!
outcome HostOperationOutcome!
worktree String worktree.create's success only: the worktree it created.
failureReason String FAILED only: why, 1 to 2000 characters.

ResumeSessionInput

1956 — resumeSession's optional input. Provenance for a session the redemption starts; on an open session it resumes, only llmModel and family are refreshed (#2086).

Field Type Description
session ID Pick one of a CHOOSE answer's candidates by its sessionId.
description String What the next session is about, when the redemption starts one (its plan).
tool String Recorded on a session the redemption starts. Never replaces the tool of a session it resumes.
host String Recorded on a session the redemption starts only.
llmModel String Recorded on a session the redemption starts, and refreshed on an open session it resumes (#2086). Omitted or null never clears.
family String Recorded on a session the redemption starts, and refreshed on an open session it resumes (#2086). Wins over the family a model implies; an invalid token is refused before any claim is spent.
effort EffortLevel #4291: recorded on a session the redemption starts, and refreshed on an open session it resumes. Omitted or null never clears.
transcriptPath String Recorded on a session the redemption starts only.
expectedWorkerId ID #3822 (hrn:node:hadronmemory.com:specs:cor:agt:020:03) — the worker the caller expects to recover, e.g. the worker a CLI worktree was last bound to. Narrows the resume to that worker: its claim or live session binds even when another worker's waits too, and a CHOOSE lists only its candidates. When nothing of that worker's waits but a claim or live session of another worker of the caller's does, the call refuses RESUME_REFUSED with extensions reason WORKER_MISMATCH, picked (true when `session` chose that other worker's item), expectedWorkerId, expectedWorkerName (null unless the caller may read that worker), foundWorkerId, foundWorkerName and foundSource (CLAIM or LIVE_SESSION), before any write: no claim is consumed and no session is started, ended or touched. With nothing of the caller's waiting the answer stays NOTHING_TO_RESUME. Omitted or null: unchanged. Blank or not an id (a URN or a name): BAD_USER_INPUT, before any read.

ScopeFilter

Filter for the uniform scopes() list. Clauses AND-combine and only narrow the caller's readable set. ownerType + ownerRef name one owner; appRef selects the App's whole CONTEXT (its own scopes, its installed Agents', its organization's) — what a bare name would resolve against there.

Field Type Description
ownerType ScopeOwnerType
ownerRef ID ID or URN of the owner (with ownerType).
appRef ID ID or URN of an App — the resolution context.
name String

SearchReplaceInNodesInput

Bulk literal/regex search-and-replace across selected nodes.

Selection is a union — at least one of 'nodeIds' or 'memoryIds' is required: - nodeIds: explicit nodes (IDs or fully-qualified URNs). - memoryIds: every live node in those memories (IDs or URNs). - prefix: further restrict the memoryIds set to the node at 'prefix' plus its descendants, matched on colon loc-path boundaries (so 'auth' matches 'auth' and 'auth:tokens' but not 'authoring'). Requires 'memoryIds' — loc is only unique within a memory.

Matching is literal substring by default; set 'regex: true' to treat 'oldText' as a RegExp source (and 'newText' as a replacement pattern with dollar-sign backrefs). 'caseInsensitive' toggles case folding. Matching is always global.

Set 'dryRun: true' to get per-node/per-field match counts WITHOUT writing.

Field Type Description
authoredWith AuthoredWithInput #1328 — the author task this write worked from, required when the node's role rule names one (before and after the write). See AuthoredWithInput.
oldText String! Text (literal) or RegExp source (regex mode) to find. Must be non-empty.
newText String! Replacement. May be empty (deletes the matched text). Regex mode honors dollar-sign backrefs.
nodeIds [ID!] Explicit node IDs or fully-qualified URNs.
memoryIds [ID!] Memory IDs or URNs — selects every live node in each.
prefix String Loc-prefix filter applied within 'memoryIds' (parent loc + descendants).
fields [NodeTextField!]! Which text fields to search. At least one required.
caseInsensitive Boolean
regex Boolean Treat oldText as a RegExp source and newText as a replacement pattern.
dryRun Boolean When true, report matches without writing anything.
reason String Why this change was made — recorded on each changed node's revision-history snapshot (NodeRevision.revLabel, #620; historically it squatted in editedBy), mirroring hadron_update_node's reason arg.

SelectedSkillFilePlanInput

Plan installed individual skill files for explicit task refs; plugin exports use skillPlan.

Field Type Description
nodes [String!]! Nonempty node IDs or fully qualified node URNs. Relative locs are refused.
host String
files [SkillFileFactsInput!]
force Boolean

SessionInput

Field Type Description
id String!
type String
repo String
branch String
prNumber Int
customerId String
language String
llmModel String
parentSessionId String
prevSessionId String
transcriptPath String #928 coding-session provenance.
host String
tool String
family String #1707 / hrn:node:hadronmemory.com:specs:cor:agt:060:04: the model family this session runs as, e.g. claude, codex or glm (a lowercase token). Omitted: derived from llmModel first, then tool — tool alone never classifies claude-code, since GLM runs inside it too — and a session nothing classifies gets no family, so its worker is not matched to queued tasks until one is given. A matching input, never an authorization input.
effort EffortLevel #4291 (hrn:node:hadronmemory.com:specs:cor:agt:060:04): the effort this session runs at, as the launcher applied it; NOT_APPLICABLE for a family with no effort control (never a refusal). Omitted on a host-started bind: the start's own effort is recorded when it names one of the scale, as its family and model are when the bind reports none. A worker-bound session's family, model and effort are also written to the worker's last-used record (Worker.lastUsed).
agentRef String #928 / cor:api:140: the role-Agent driving this session, as a PK or URN. Resolves to Session.agentId. The caller must be able to READ the agent (PUBLIC, or owner / org member) - a session is never attributed to an agent the caller cannot see. Usually omitted with workerRef, which derives it from the casting.
workerRef String #974 / cor:agt:020:03: the Worker (named casting) this session works as. Three forms resolve, told apart by SHAPE (never by trying each in turn, so a typo'd URN can't silently fall through to a roster search): - the worker's NAME ("Iris") — #990. Unique per App, case-insensitively, matched with the DATABASE's lower(), the expression workers_app_name_uniq indexes. With appRef, an App-key credential or an MCP active-App selection, lookup stays within that App. With no App, #1597 searches only live Apps the caller may bind into: exactly one non-retired match binds; none refuses WORKER_NOT_FOUND; several refuse SESSION_WORKER_NAME_AMBIGUOUS with candidates (worker id/URN, name, App, role and holder). Nothing is bound on ambiguity: choose an id or URN. Candidate discovery reuses App participation and user-owned-App holding rules; it grants no new bind authority. The staff read gate precedes name lookup (hrn:node:hadronmemory.com:specs:cor:agt:020:00). Which refusal you get depends on WHERE the denial happens, and clients should not assume one code covers both: a caller who supplied appRef has already been checked against the same participant predicate, so an outsider is refused FORBIDDEN there, before any name is read. Only a denial at the in-branch staff gate — reachable when the App came from an App-key credential rather than appRef — is masked as WORKER_NOT_FOUND, indistinguishable from an App with no such worker. - the worker's URN (hrn:worker:<root>:<app-slug>:<slug>, #991); the URN's leaf is the derived slug, never the display name (cor:agt:020:02). - the worker's id. Resolves to Session.workerId, and stamps Session.agentId with the worker's role-agent. The worker must belong to the session's App: with appRef (or an App-key credential) it must match the worker's App; without one, the worker's App becomes the session's, behind the same membership gate as appRef. A retired worker refuses (WORKER_RETIRED). #1937: an id or URN naming a worker in an App the caller cannot read refuses exactly like an absent ref (WORKER_NOT_FOUND, same message and extensions), so no other refusal here tells an outsider the worker exists. The one exception is the worker the caller's own launchGrant names (see launchGrant). #940: a worker with a LIVE session (the shared derived liveness predicate) refuses WORKER_TAKEN — extensions carry workerId, sessionId, lastDriver, lastSeenAt, everything the takeover prompt needs — unless force is true (informed takeover, cor:agt:020:03: show who last drove it, proceed only on explicit override, never silently).
reportsTo String #1726 — the worker this bind's worker reports to: an id, URN or name of a worker in the session's App. Sets it in the same step as the bind (a spawn brief), only when the worker reports to nobody or already to this one; naming a different worker is refused (WORKER_REPORTS_TO_HELD) unless the caller manages the App, and refuses the bind with it. Omitted leaves the value unchanged. Needs workerRef and a person behind the request.
force Boolean #940: take over a worker whose binding would otherwise refuse WORKER_TAKEN. Only meaningful with workerRef. Clients must surface the WORKER_TAKEN payload (who last drove it, when) before retrying with force - that IS the informed-takeover contract; force exists so the override is explicit, never the default.
launchGrant String #1709 — the single-use launch grant a host passed to the agent it started (hrn:node:hadronmemory.com:specs:cor:agt:070:08). Redeemed with the HOLDER's own token: it binds that worker on the holder's behalf and records the launching host, operation and task; the hold is unchanged. workerRef may be omitted (the grant names the worker). Refused LAUNCH_GRANT_INVALID when unknown, expired, used or not minted for the caller (an App key never redeems one); LAUNCH_REFUSED, failing the start with the reason, when the hold changed, the holder may no longer hold the worker, or it already has a live session. Never forced: with force it is BAD_USER_INPUT. The grant's own worker skips the #1937 worker read gate, because the grant already told its holder that worker exists: a holder who has lost the App gets LAUNCH_REFUSED with its reason rather than WORKER_NOT_FOUND, and so may learn that this one worker was retired (#1945). Any other workerRef sent with a grant is gated first.
startSettingsApplied Boolean #4306 — with launchGrant only: whether the host applied the run settings (family, model, effort) its start named (hrn:node:hadronmemory.com:specs:cor:agt:070:08). false: the start's settings were NOT applied (an exec-path worker runs its own fixed command), so this bind inherits none of them from its start: the session holds only the family, model and effort this bind itself reports (a family derived from its own llmModel or tool included), and the worker's last-used record and the task's applied settings follow the session, so a record the worker already had stays as it was (a null never clears it). true, null or omitted: a bind that reports none runs as its start said, as before, so a client that never sends this is unaffected. false without a launchGrant is refused BAD_USER_INPUT before anything is written, because there is no start to qualify.
plan String The session's stated intent (Session.plan) - what this session is about. MCP's hadron_start_session description lands here.
appRef String #943 / cor:api:140: the App this session is a unit of work for, as a PK or URN. Resolves to Session.appId - the pivot that was previously stamped ONLY from an App-key credential, which made a user-started session structurally unable to satisfy the team-chat authorship gate (cor:agt:020:04 condition b, SESSION_NOT_IN_APP). The caller must be a member of that App: an AppMember at any role, an org member with CONTRIBUTOR+ on its owning org, or the owner of a user-owned App. Unknown or deleted App: BAD_USER_INPUT; non-member: FORBIDDEN. An App-key credential wins - if the caller authenticated as an App and appRef names a DIFFERENT App, the call is refused (SESSION_APP_MISMATCH). Uninstalled Apps differ by ref form, because App URNs are only unique among ACTIVE rows (spec 021 FR-027: one live App plus N uninstalled history rows may share a URN). By URN an uninstalled App is simply not found - BAD_USER_INPUT - since there is no single row the URN names; by PK it is found and refused APP_UNINSTALLED.

SetAgentAssetUploadEnabledInput

Field Type Description
agentUrn String! Agent reference. Accepts the entity's ID (CUID / 32-char hex) or its URN (per spec 007 ID-or-URN dispatch). URN inputs MUST be fully qualified (org:agent) per spec 022 — relative-form URNs are rejected as GraphQL errors with extensions.code "URN_NOT_QUALIFIED".
enabled Boolean!

SetAiModelPriceInput

Field Type Description
provider String!
model String!
tier Int Pricing tier 1-3; defaults to 1.
inputMicroCentsPerMTok String!
outputMicroCentsPerMTok String!
markupBasisPoints Int Per-tier debit markup in basis points (2500 = 25%); omit to fall back to the CREDIT_MARKUP_PERCENT env default.
effectiveAt String Defaults to now. Appends a new effective-dated row - never mutates.

SetHostWorkerAvailabilityInput

Field Type Description
appRef String!
worker String! A worker this host registers: its id, URN or name within the App.
state AvailabilityState!
reason AvailabilityReason UNAVAILABLE only: OUT_OF_TOKENS or HOST_DOWN.
until DateTime Optional, UNAVAILABLE only, in the future.

SetHostWorkerTerminalsInput

Field Type Description
appRef String!
reports [WorkerTerminalReportInput!]! One to 200 reports, a worker at most once.

SetModelFamilyAvailabilityInput

Field Type Description
appRef ID!
family String! A lowercase token, e.g. claude or codex.
state AvailabilityState!
reason AvailabilityReason
until DateTime

SetQuotaLimitInput

Field Type Description
orgRef String! Org - ref: PK or URN.
appRef String Optional app scope - ref: PK or URN; must belong to the org. Omit to set the org-level limit.
action String! run.execute, llm.tokens, sms.send, or email.send.
limit Int! Non-negative integer; 0 pauses the scope (every launch denies QUOTA_EXCEEDED).

SetRateLimitPolicyInput

Complete limit triple; mode omitted or null preserves (hrn:node:hadronmemory.com:specs:cor:api:210:01).

Field Type Description
fieldClass RateLimitFieldClass!
expectedVersion Int!
principalLimit Int!
keyLimit Int!
ipLimit Int!
enforcementMode RateLimitEnforcementMode
changeReference String!

SetTeamStopSignalInput

Field Type Description
appRef String!
level StopSignalLevel!
scope StopSignalScope!
worker String WORKER and TEAM: the target worker (a team by its head).
host String HOST: the host's id. A host key may omit it: its own host is taken from its binding.
until DateTime When it ends on its own; later than now. Omitted: until lifted.

SetWorkerAvailabilityInput

Field Type Description
worker String! The worker: its id or URN, or its name together with appRef.
appRef ID
state AvailabilityState!
reason AvailabilityReason Required when UNAVAILABLE; refused when AVAILABLE.
until DateTime Optional, UNAVAILABLE only, in the future.

SetWorkerLeaveAloneInput

Field Type Description
worker String! The worker: its id or URN, or its name together with appRef.
appRef ID
leaveAlone Boolean!
reason String Optional, only when marking: why the sweep leaves this worker alone. At most 500 characters.

SkillFileFactsInput

What the client saw of ONE file on disk. The server never reads the caller's disk.

Field Type Description
dirName String! The directory the skill occupies — compared against the node's stored name.
nodeId String The id value from the provenance header; omit on a header generation that predates it.
sourceUrn String The source URN from the provenance header.
headerHash String The hash value from the header; omit for a legacy header that carries none.
fileHash String The hash the client computed over the file itself.
revision Int The positive rev=N value from provenance. Null means an older artifact omitted it.
parseFailed Boolean True when the file exists and could not be parsed.
hasExtraFrontmatter Boolean True when the file carries frontmatter keys the renderer never writes.

SkillPlanInput

Field Type Description
intent SkillPlanIntent!
memories [String!] Memory refs for LINT/STATUS only. EXPORT refuses this field, even an empty list.
scopeRef ID Persisted Scope ID for a narrowed EXPORT. Omit for unscoped export; explicit null refuses. Membership is resolved afresh for each call.
host String Target host, named by its D12 declaration key verbatim. Supported hosts: claudeSkill, codexSkill. Default: claudeSkill. One host per call; the plan reads that host's declaration and applies its limits, and the retired top-level skill/claudeSkill keys alias to claudeSkill only. An unknown host is refused with BAD_USER_INPUT naming the supported hosts, never judged as another host and never answered with an empty plan.
files [SkillFileFactsInput!] What the client found on disk. Empty for lint, which touches no disk.
force Boolean With EXPORT only, explicitly override local-edit or missing-provenance-ID protection for this invocation.

SpecSearchReplaceInput

Replace text in explicit unminted nodes of one memory. A dry run returns a plan; apply must present that exact plan and refuses if any selected row, protection, match, or mint state changed. A minted target node is refused, even when other nodes in the memory are unminted. Other governed kinds and protected addresses are skipped; ordinary nodes need not carry the spec role. Generic replacement keeps its governed-node protections.

Field Type Description
authoredWith AuthoredWithInput #1328 — one claim for every changed spec. See AuthoredWithInput.
memoryRef ID!
nodeIds [ID!]!
oldText String!
newText String!
fields [SpecTextField!]!
caseInsensitive Boolean
regex Boolean
wordBoundary Boolean Literal mode only; matches the CLI's default ASCII word-boundary behavior.
dryRun Boolean
expectedPlan String Required for apply; copied from the exact dry-run response.
maxNodesChanged Int Refuse the entire apply when more nodes would change.
reason String

TickerInput

Field Type Description
name String!
cadenceSeconds Int!
anchorAt DateTime Tick counting starts here. Defaults to now.
quietHours JSON
channelIds [ID!]
relevance TickerRelevance
reasons [TickerReason!] Absent on create = [READ_TEAM_CHANNEL]; an empty list is refused. On update, absent = unchanged.
enabled Boolean

TickerPatch

Absent fields are unchanged. Use clearQuietHours / clearChannels to remove those.

Field Type Description
name String
cadenceSeconds Int
anchorAt DateTime
quietHours JSON
clearQuietHours Boolean
channelIds [ID!]
clearChannels Boolean
relevance TickerRelevance
reasons [TickerReason!] Absent on create = [READ_TEAM_CHANNEL]; an empty list is refused. On update, absent = unchanged.
enabled Boolean

TriggerAppRunInput

Field Type Description
budgetTokens Int Optional per-run token limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
budgetActions Int Optional per-run action limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
appRef String! App — ref: PK or fully-qualified URN.
agentRef ID The Agent the run is served as (PK or URN), installed in the App. Omit to use the App's single installed Agent; an App with several refuses with RUN_AGENT_REQUIRED (#2735).
entryNodeUrn String!
eventData JSON
runAsSelf Boolean
aiConfigName String

UnassignHostWorkerInput

Field Type Description
appRef String!
hostId String!
worker String!

UpdateAgentScheduleInput

Field Type Description
budgetTokens Int Optional per-run token limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
budgetActions Int Optional per-run action limit (#2479): positive, no greater than the platform default at save; narrowed again at launch. Null uses the default.
name String
cron String Providing cron switches the schedule to recurring (clears runAt).
runAt String Providing runAt switches the schedule to one-shot (clears cron). At most one of cron / runAt per call.
timezone String
entryNodeUrn String
agentRef String Agent — ref: PK or URN; must be installed in the App.
runAsSelf Boolean
eventData JSON
policy JSON
aiConfigName String
enabled Boolean
scopeRef ID Spec 049: set the trigger's scope (id or name in the App's context); an empty string clears it back to 'app'.

UpdateAgentTaskInput

2645: named fields replace; omission leaves unchanged. Title cannot be empty. Source and lifecycle fields are fixed.

Field Type Description
title String
description String
tags [String!]
requirements AgentTaskRequirementsInput
properties JSON #2420 (hrn:node:hadronmemory.com:specs:cor:agt:050:28): omitted leaves the value, a JSON object replaces the whole of it (no merge), null clears it. Writable by the task's owner, a worker the owner reports to, whoever manages the App, and the task's assignee; an assignee's update may name this field and no other. Refused on a finished or cancelled task. A non-object is PROPERTIES_NOT_AN_OBJECT, over 16 KiB of canonical JSON PROPERTIES_TOO_LARGE, a violation of the Team Agent's schema:task-properties PROPERTIES_SCHEMA_VIOLATION, an unusable schema PROPERTIES_SCHEMA_UNUSABLE.
startBy DateTime Reanchors only the not-started deadline; null clears the explicit deadline. Existing alarms stay raised.
finishBy DateTime #2648 (hrn:node:hadronmemory.com:specs:cor:agt:050:14): set or change the finish-by deadline (refused BAD_USER_INPUT if in the past or earlier than startBy), or null to clear it, which brings the ordinary stall windows back from this edit. Either change ends the current finish-by episode. Setting only startBy is refused if it is later than the finish-by time.
closeSessionWhenDone Boolean Null clears to false; omission preserves the stored choice.
references [AgentTaskReferenceInput!] #2649 (hrn:node:hadronmemory.com:specs:cor:agt:050:09): a list replaces the whole list, order kept; null or an empty list clears it; omission leaves it. The task.edited event names references, never the values.

UpdateChannelInput

Field Type Description
name String
description String

UpdateMemoryConfigTemplateInput

1325 part (c) — change a template. An omitted field is unchanged;

description null clears it. rules, when given, REPLACES the template's rules in one transaction.

Field Type Description
name String
description String
required Boolean
orgDefault Boolean #3426 — an ORGANIZATION-owned template applied to every new org `knowledge` or `group` memory at its creation (`createMemory` only; never clone, extract, App, install, agent or chat creation). A starting configuration, not a boundary. User-, App- and server-owned templates refuse true (BAD_USER_INPUT, reason ORG_DEFAULT_ORG_ONLY). At most 10 live defaults per organization (ORG_DEFAULT_LIMIT). Setting it true validates every reference as readable to the ORGANIZATION as well as the saver (NODE_NOT_FOUND otherwise); clearing it never validates. Proposed addition built on the #3426 gate to hrn:node:hadronmemory.com:specs:cor:api:290.
rules [CreateNodeRoleRuleInput!]

UpdateNodeInput

Input for updateNode. Identify the target by 'id' (PK or fully-qualified node URN) XOR ('memoryId' + 'loc') — both selectors, or neither, is an error (spec 039 Phase 0 D2). updateNode never creates and never moves (D3). Every content field is optional: omitted = preserved (D4).

Field Type Description
authoredWith AuthoredWithInput #1328 — the author task this write worked from, required when the node's role rule names one (before and after the write). See AuthoredWithInput.
id String The node to change: PK (CUID / 32-char hex) or fully-qualified node URN (hrn:node:<root>:<memory>:<loc>). XOR with memoryId+loc.
memoryId String Selector, with 'loc': the target's memory (ID or fully-qualified URN). XOR with 'id'.
install InstallTargetInput #2044 — selector, with 'loc', in place of 'memoryId': the App's install memory. Creates nothing (the first createNode does). XOR with 'id'.
loc String Selector, with 'memoryId': the target's current loc. Not writable here — moveNode relocates.
expectedRevision Int Optional optimistic-concurrency precondition (#937). When supplied, the update is applied only while the node's current live revision still equals this positive 32-bit integer. A mismatch refuses atomically with NODE_WRITE_CONFLICT; omitting it or passing null preserves last-write-wins compatibility. Read the baseline from Node.revision.
name String Omit to preserve (D4).
nodeType String
objectType String #725 — collection discriminator (e.g. "competitor"). Omit to preserve; null to clear.
isRunnable Boolean Whether this node can be run as a task by hadron_run_task (cor:api:060). Omit to preserve.
role String #1201 — what this node is FOR (open string). NOT 'nodeType' and NOT 'objectType' — see Node.role. Omit to preserve; null to clear. A GOVERNED value requires that kind's own door, and so does editing a node that ALREADY carries one: the gate reads the resulting state, not the change.
alias String
description String
abstract String Paragraph-length summary of this node — see Node.abstract for the surfacing contract. Omit to preserve; null to clear; string to replace. Empty + whitespace-only normalize to null. Cap is 2000 characters.
content String
contentType String MIME type of content (#476/#488, spec cor:cnv:010:01): 'text/markdown' (default) stores as-is; 'text/html' converts captured DOM to Markdown; 'application/pdf' extracts a PDF's text layer to Markdown (send 'content' as raw base64 — a PDF is binary; scanned/image-only PDFs error). The conversion runs before storage and fills properties.title from the extracted title when not supplied. Consumed at write time — never persisted. Any other value is rejected.
seq Int
tags [String!] Omit to preserve existing tags (issue #235); supply to replace the set.
properties JSON
data JSON
ownerRepo String
llmModel String
aiAgent String
edges [NodeEdgeInput!] Replace all outgoing edges when provided (omit to leave edges unchanged)
reason String Why this change was made — recorded on the revision-history snapshot (NodeRevision.revLabel, #620; historically it squatted in editedBy), mirroring hadron_update_node's reason arg so CLI and MCP edits leave equally-traceable history.

UpdateNodeRoleRuleInput

1325 — change a rule. An omitted field is unchanged. A reference given as

null or an empty string CLEARS it; validateBy null clears it. The role itself is the rule's identity and cannot be changed: delete and re-create instead.

Field Type Description
authorTaskRef ID
validationTaskRef ID
descriptionNodeRef ID
strictSubRoles Boolean
writers NodeRoleWriters
validateBy ContentValidator
enabled Boolean

UpdateRegisterEntryInput

Field Type Description
role RegisterRole
mentionOnly Boolean
description String

UpdateScopeInput

All optional. memoryRefs, when passed, REPLACES the list (it is the new order).

Field Type Description
name String
description String
memoryRefs [ID!]

UsageEventInput

Field Type Description
type String!
nodeLoc String
actionArgs JSON
sessionId String
model String
tokensIn Int
tokensOut Int

UserFilter

Filter for the uniform users() list (#473). For a non-platform-admin caller 'query' is REQUIRED (a blank/omitted query returns an empty page) and matching follows hrn:node:hadronmemory.com:specs:cor:acl:070:02: public identifiers (handle, githubUsername) match by substring, email by exact equality, and name only for platform admins or live co-members of an organization. Platform ADMIN/OWNER may omit 'query' for the full user list.

Field Type Description
query String

WorkerTerminalReportInput

2771 — one worker's terminal report. There is no free-text field.

Field Type Description
worker String! A worker this host registers: its id, URN or name within the App.
status WorkerTerminalState!
prompt WorkerTerminalPrompt!
reason WorkerTerminalReason Required for locked and dark; refused for busy and idle.
lastTurnAt DateTime When the worker's last turn ended, not after checkedAt.
checkedAt DateTime! When the host classified the terminal, not more than two minutes ahead of the server.
repair WorkerTerminalRepair #4041 (V82) — the outcome of the host's repair of a dark worker. Valid only with status dark; on a busy, idle or locked report that worker's report is refused (REPAIR_NOT_DARK) and the rest of the batch is stored.
repairReason WorkerTerminalRepairReason #4247 — why the relaunch was refused or failed: required with RELAUNCH_REFUSED and RELAUNCH_FAILED (from that outcome's own set), refused (REPAIR_REASON_INVALID) with any other outcome or none. Stored on the report with the outcome.
attempt Int The relaunch's attempt number, at least 1: required with RELAUNCHED, RELAUNCH_REFUSED and RELAUNCH_FAILED, refused (REPAIR_ATTEMPT_INVALID) otherwise.
contextTokens Int #4225 — the size of the worker's context in tokens, measured on the host: a whole number from 1. Null or omitted when the host cannot measure this worker, never 0. A number only: no transcript text is sent.
contextMeasuredAt DateTime #4225 — when the host measured contextTokens, not more than two minutes ahead of the server. Sent exactly when contextTokens is.

WorkerWakeSettingsInput

Field Type Description
mentions MentionWake
pausedUntil DateTime
clearPause Boolean

Enums

AccessSource

issue #323: where a single grant in an EffectiveAccess result comes from.

Value Description
PLATFORM_ROLE Platform ADMIN/OWNER.
ORG_ROLE ADMIN/OWNER (or, for org-readable knowledge, any Role) of the owning org.
MEMORY_PRINCIPAL personal/private memory owner (Memory.userId).
MEMORY_MEMBER group-class team membership row (MemoryMember).
MEMORY_SHARE personal-class cross-user grant (MemoryShare).
PRINCIPAL_GRANT individual action grant (PrincipalGrant, cor:acl:040:06) - clone/delete capabilities on top of the role bundle.
NODE_INHERITED node inherits its memory's access.
APP_MEMBER AppMember row.
AGENT_SUBSCRIPTION active AgentSubscription, or an org-level AgentOrgGrant the user inherits.
AICONFIG_OWNER admin of the AI config's owning entity.
PUBLIC_VISIBILITY resource is publicly / universally visible.

AccountUsageConfidence

3820 — how many of the 1h, 6h and 24h lookbacks had data: one is LOW, two MEDIUM, three HIGH.

Value Description
LOW
MEDIUM
HIGH

AccountUsageReason

3820 — why a window is not PROJECTED. UNKNOWN: NO_HISTORY, NO_WINDOW (no snapshot reports this window), STALE (newest

snapshot over 60 minutes old), NO_RESET, RESET_PASSED, NO_WORKERS_CONFIGURED (a what-if needs the account's workers), WHATIF_SOURCE_UNKNOWN (the moved worker's burn is not known), HISTORY_INCOMPLETE (#3842: the account was named without both host and family and the server could not finish checking whether another history shares the label; every window of it carries this reason and no range; so do the what-if windows of such an account, and the adjusted target windows of a move from one. hrn:node:hadronmemory.com:specs:cor:agt:140:03). INSUFFICIENT_DATA: LOW_USE (under 5% used), TOO_FEW_SNAPSHOTS (fewer than 3, or spanning under an hour).

Value Description
NO_HISTORY
NO_WINDOW
STALE
NO_RESET
RESET_PASSED
NO_WORKERS_CONFIGURED
WHATIF_SOURCE_UNKNOWN
HISTORY_INCOMPLETE
LOW_USE
TOO_FEW_SNAPSHOTS

AccountUsageShape

3820 — FLAT is a constant burn rate; WEEKLY follows the hour-of-week shape of at least a week of history.

Value Description
FLAT
WEEKLY

AccountUsageStatus

3820 — PROJECTED has a range; INSUFFICIENT_DATA has none (never a run-out time); UNKNOWN has no trustworthy data.

Value Description
PROJECTED
INSUFFICIENT_DATA
UNKNOWN

AccountUsageWindow

3820 — a subscription account's rate-limit windows: the 5-hour and 7-day ones, or OTHER for a family's window of another length (see lengthMinutes).

Value Description
FIVE_HOUR
SEVEN_DAY
OTHER

ActInstructionKind

Instruction claim for one act, recorded rather than verified for authorship, recency or reuse; the holder answers for the claim (hrn:node:hadronmemory.com:specs:cor:dmo:050:12, ruling 0096).

Value Description
TEAM_CHAT_MESSAGE
TASK
LIVE_CHAT

ActionRegisterIndexState

3287 — one code's answer in the action-register index (hrn:node:hadronmemory.com:specs:cor:agt:110:03).

Value Description
MAPPED
UNRESOLVED
UNMAPPED

AgentLifecycle

4224 (S3 of #4229): how long an Agent's workers run.

Value Description
LONG_LIVED The worker's process should always run (the default, and the behaviour before this field existed).
SHORT_LIVED The worker's process should run only while it is the assignee of a pending or started task (one waiting on its child tasks included).

AgentOfferReasonCode

2246 - why an Agent is not ready to be offered; the values are the clone refusal's codes (hrn:node:hadronmemory.com:specs:cor:dmo:050:19).

Value Description
AGENT_NOT_PUBLIC
AGENT_RETIRED
CLONE_LINKED_MEMORY_ENCRYPTED
CLONE_LINKED_MEMORY_UNREADABLE
CLONE_BASE_UNUSABLE
CLONE_IMPORT_UNUSABLE

AgentProcessKind

1892 (hrn:node:hadronmemory.com:specs:cor:dmo:050:16) - how an Agent takes part in a process.

Value Description
STARTS Listed in the Agent's processes index: a process it starts or owns.
INVOLVED Derived: the process has a stage edge to one of the Agent's tasks.

AgentSchedulePreviewOutcome

Value Description
ADOPTABLE The automation can be adopted: summary and hash are set, reason is null.
CANNOT_BE_ADOPTED Create would store this schedule UNADOPTED: summary and hash are null and reason says which kind.
GRANT_REQUIRED #3483: the caller is a worker-bound session and create would be refused with TRIGGER_GRANT_REQUIRED: it holds no live, signed schedule.create grant for this entry node in this App (hrn:node:hadronmemory.com:specs:cor:agt:010:01). Summary, hash and reason are null. Only while the grant check is on.

AgentSchedulePreviewReason

Value Description
MEMORY_UNREADABLE The entry or something it routes to is missing or not readable by you or by the run. A missing entry and an unreadable one answer identically.
OTHER Readable, but the graph is encrypted, outside the organization or over the consent bounds.

AgentTaskCreateStatus

The statuses a task may be CREATED in (#1754, hrn:node:hadronmemory.com:specs:cor:agt:050:02): every other status is reached by a move.

Value Description
BACKLOG
PENDING

AgentTaskExternalIdChangeKind

4084 (hrn:node:hadronmemory.com:specs:cor:agt:120): what a change to a task with an external id was.

Value Description
ASSIGNED task.assigned, or the platform's assignment.matched
REASSIGNED
HANDED_BACK The assignee handed the task back to the queue.
CANCELLED
FINISHED
RELEASED The external id was released (cleared); externalId is the released id.

AgentTaskFindingDispositionCode

2663: every code resolves the finding, including deferred (hrn:node:hadronmemory.com:specs:cor:agt:050:30).

Value Description
fixed
accepted
deferred
rejected

AgentTaskFindingSeverity

2662: severity is shape only, never matcher, authorization or alarm input (hrn:node:hadronmemory.com:specs:cor:agt:050:30).

Value Description
P1
P2
P3
note

AgentTaskHandBackCode

2651: why an assignee handed a started task back, a closed set (hrn:node:hadronmemory.com:specs:cor:agt:050:29,

Proposed details). MISSING_INPUT: something the work needs is not there. CANNOT_DO: the worker lacks the capability. REFUSED: a policy or safety refusal. OUT_OF_SCOPE: the work is not what this task's role does. DUPLICATE: the same work is already tracked elsewhere.

Value Description
MISSING_INPUT
CANNOT_DO
REFUSED
OUT_OF_SCOPE
DUPLICATE

AgentTaskMatchSkipReason

Why a failed match skipped a candidate (#3816, V21). Closed and additive: values are added, never renamed. STOP_SIGNAL names a matcher condition V21 lacked. There is no value for a bound, quiet worker: hadron-server#3815 removes that exclusion. NO_LONGER_FREE (#3855, V59) is a candidate the snapshot found free that the final assignment check refused; it carries no other value.

Value Description
RETIRED
USES_NO_TASKS
ENDING_SESSION
HOLDS_TASK
UNAVAILABLE
FAMILY_UNAVAILABLE
STALLED
NO_FAMILY
NOT_HELD
FAMILY_EXCLUDED
NAME_EXCLUDED
TIER_BELOW_MINIMUM
TIER_UNKNOWN
MODEL_GROUP_MISMATCH
STOP_SIGNAL
NO_LONGER_FREE

AgentTaskMatchedBy

2421 experimental symptom search: membership in the hybrid ranking inputs.

Value Description
VECTOR Ranked by the vector retriever.
KEYWORD Ranked by the keyword retriever.
BOTH Ranked by both retrievers.

AgentTaskPartyKind

Whether a task party is a team Worker or a person.

Value Description
WORKER
USER

AgentTaskReferenceKind

2649 (hrn:node:hadronmemory.com:specs:cor:agt:050:01): what a task reference points at, which fixes the form its target takes.

Value Description
ISSUE An absolute https URL of an issue. No owner/repo#n shorthand.
PULL_REQUEST An absolute https URL of a pull request.
NODE A node URN (hrn:node:...).
TASK An agent-task URN (hrn:agenttask:<root>:<app-slug>:<task id or handle>), never a bare handle.
URL An absolute http or https URL.

AgentTaskSessionEndResolution

Value Description
ENDED
END_ISSUED
NO_LIVE_HOST

AgentTaskStatus

An agent task's status (hrn:node:hadronmemory.com:specs:cor:agt:050:02). FINISHED and CANCELLED are the end states. BACKLOG (#1754) is parked: no assignee, never matched, never waited on, no alarms; assigning it or making it ready moves it to PENDING.

Value Description
BACKLOG
PENDING
STARTED
FINISHED
CANCELLED

AgentTeamEventSeverity

Value Description
ALARM

AgentType

Value Description
ASSISTANT
CHATBOT

AgentVisibility

035-visibility-enum-cleanup: agents have their own visibility enum, decoupled from MemoryVisibility. PERSONAL is the creator-only draft state.

Value Description
PUBLIC
ORGANIZATION
PERSONAL

AgentlessEndReason

4292: the closed proofs a host gives for ending a session itself.

Value Description
AGENT_ABSENT No agent process runs in the worker's worktree.

AiApiStyle

1373: the wire protocol of an OpenAI-compatible provider.

Value Description
CHAT_COMPLETIONS POST {endpoint}/chat/completions — what most OpenAI-compatible hosts serve (the glm default).
RESPONSES POST {endpoint}/responses — OpenAI's Responses API (the openai default).

AiConfigOwnerType

036-ai-service-config: which entity owns an AiServiceConfig. Exactly one owner per config (DB-enforced).

Value Description
HADRON_SERVER
ORGANIZATION
APP
AGENT

AiConfigTestKeySource

1378: which key a test used; NONE when there was none to use.

Value Description
SAVED
OVERRIDE
PLATFORM A HADRON_SERVER config with no stored key: the server's own credential for that provider served the call, as it serves a run (#1385).
NONE

AiConfigTestValueSource

1378: where a tested value came from.

Value Description
SAVED
OVERRIDE

AppGrantName

1747, #3308 — the closed list of named App grants (hrn:node:hadronmemory.com:specs:cor:agt:080:24). Giving any grant stays person-only (hrn:node:hadronmemory.com:specs:cor:dmo:050:12).

Value Description
TICKER_SUBSCRIBE_WORKERS Subscribe and unsubscribe OTHER workers of the App, at any cadence.
WORKERS_STAFF Named permission for headless casting, retiring and deleting workers; the holder's own staffing rights still apply. Provisioned before the separate #3308 enforcement rollout.
APP_MEMBERS Named permission for headless App-member add/remove; the holder's own member-management rights still apply. Provisioned before the separate #3308 enforcement rollout.

AppMembershipRole

Value Description
OWNER
ADMIN
CONTRIBUTOR
READER

AppMemoryKind

Value Description
shared
user
none

AppMemorySourceKind

Value Description
AGENT_SYSTEM The system memory of an Agent installed in this App.
AGENT_LINK A memory linked to an Agent installed in this App.
INHERITED_BASE A base Agent's system memory, with nodes inherited by an installed Agent's system memory (hrn:node:hadronmemory.com:specs:cor:dmo:050:14).
TEAM_SPACE The App's own team space, listed for App participants only.
APP_MEMORY A free-standing app memory of this App, the kind createAppMemory makes: app-class, no Agent links it, not the team space. Listed for App participants only, never for an org reader who is not one (hrn:node:hadronmemory.com:specs:cor:dmo:050:17, hadron-server#2861).

AppRunSortField

Orderable columns on the appRuns list (#833). Reuses the shared SortDirection enum. Default createdAt desc — existing callers depend on newest-first.

startedAt / finishedAt are NULLABLE (a PENDING run has neither); nulls sort LAST in both directions, so unstarted runs never crowd out the rows an operator asked to see. Every sort carries an id tiebreak so offset paging is deterministic.

Duration (finishedAt - startedAt) is deliberately absent: it has no stored column and Prisma cannot order by a computed expression, so it needs a generated column of its own - tracked separately rather than half-shipped.

Value Description
createdAt
startedAt
finishedAt
status

AppRunStatus

Value Description
PENDING
RUNNING
COMPLETED
FAILED
TIMED_OUT
CANCELLED

AppRunTriggerKind

Value Description
SCHEDULE
WEBHOOK
MANUAL
INTEGRATION
SPAWN

AppType

Value Description
WORKSTATION
CHATBOT
AGENT
AUTOMATION
CLOUD
IOT

AssetScanStatus

Value Description
PENDING
CLEAN
BLOCKED

AuthenticationStatus

What the credential presented on THIS request came to (hrn:node:hadronmemory.com:specs:cor:aut:010:05).

Value Description
AUTHENTICATED The credential resolved a user or an App.
REFUSED A credential was presented and did not authenticate. One answer for every cause, with no reason.
ANONYMOUS No credential was presented.

AutomationAdoptionState

2441: UNADOPTED = no valid adoption; ADOPTED = a valid adoption; CHANGED = the automation differs from what was adopted (computed on open only), so the next run fails AUTOMATION_CHANGED.

Value Description
UNADOPTED
ADOPTED
CHANGED

AutomationTriggerKind

Value Description
SCHEDULE
WEBHOOK
MANUAL

AvailabilityReason

Why a worker or a model family is unavailable for work (hrn:node:hadronmemory.com:specs:cor:agt:060:02; held was dropped, team chat #7449).

Value Description
STALLED
OUT_OF_TOKENS
HOST_DOWN
OTHER
RESETTING #2162 — a context reset is in progress (hrn:node:hadronmemory.com:specs:cor:agt:050:27). Set only by the platform; no caller sets it.

AvailabilitySetter

Who set a worker's availability (hrn:node:hadronmemory.com:specs:cor:agt:060:08).

Value Description
WORKER The worker itself; only ever to unavailable.
HOLDER The person holding the worker's name.
APP_MANAGER Whoever manages the App.
REPORTS_TO #1759 — the worker it reports to directly, clearing a mark the stall rule set (hrn:node:hadronmemory.com:specs:cor:agt:060:11): only to AVAILABLE.
STALL_RULE The stall rule (hrn:node:hadronmemory.com:specs:cor:agt:060:07): an alarm marked it, or its next activity cleared it.
HOST A host that registered the worker (the host-operations slice).
LAPSE #1766 — the platform, recording that an until passed (hrn:node:hadronmemory.com:specs:cor:agt:060:02): the record is then AVAILABLE, set at the instant it lapsed.
CONTEXT_RESET #2162 — the platform's context reset (hrn:node:hadronmemory.com:specs:cor:agt:050:27): it set RESETTING, or released it.

AvailabilityState

Value Description
AVAILABLE
UNAVAILABLE

BootPromptServeRefusal

2708 / hrn:node:hadronmemory.com:specs:cor:agt:040:10: why a serve would be refused now, the typed code the bind,

chat or run itself would get. BOOT_PROMPT_NOT_SIGNED occurs only where the serving App's organisation has switched signing on (setOrgBootPromptSigning, #2973) AND the deployment ships signing.

Value Description
BOOT_PROMPT_INSTALL_LICENSE_INACTIVE
BOOT_PROMPT_NOT_SET
BOOT_PROMPT_TARGET_DELETED
BOOT_PROMPT_NOT_APPROVED
BOOT_PROMPT_NOT_SIGNED

BootPromptSigningPreviewState

2973 PR2 / hrn:node:hadronmemory.com:specs:cor:agt:040:09 and hrn:node:hadronmemory.com:specs:cor:agt:040:10: what

switching signing on would do to ONE served compiled boot prompt. SIGNATURE_PENDING: the served revision's signature is pending (a first passkey's cooling-off window), so it would stop being served until the window ends. REVISION_CHANGES: the serve would fall back to changesToRevSeq, the newest older revision that is approved and signed (R35). UNSIGNED_STOPS: no approved revision is signed, so it would be refused.

Value Description
SIGNATURE_PENDING
REVISION_CHANGES
UNSIGNED_STOPS

CalendarEventResponse

Provider-neutral attendee response. NONE = invited, not yet answered.

Value Description
ACCEPTED
DECLINED
TENTATIVE
NONE

ChannelKind

What kind of feed a Channel is. CHAT today; BLOCKERS / TASKS when built.

Value Description
CHAT

ChatProbeStatus

4005: PASS = exactly ONE respond call with a string message and every required field, whichever tool choice was sent.

FAIL_TEXT_ONLY = no tool call. FAIL_OTHER_TOOL = a call to a tool that was not offered. FAIL_MULTIPLE_CALLS = more than one call. FAIL_MALFORMED = one respond call whose arguments do not fit its schema. FAIL_PROVIDER_UNAVAILABLE = the call failed or timed out, or none could be made (no key, an unbuildable config, a quota refusal). UNSUPPORTED_PROVIDER = the provider is not offered tools.

Value Description
PASS
FAIL_TEXT_ONLY
FAIL_OTHER_TOOL
FAIL_MULTIPLE_CALLS
FAIL_MALFORMED
FAIL_PROVIDER_UNAVAILABLE
UNSUPPORTED_PROVIDER

ChatScope

017-chat-visibility-and-personal-memory: a chat is created in one of two tiers, chosen by the user at chat creation and immutable thereafter. shared chats live in the App's app-class memory. private chats live in the user's personal-class memory, OR in a knowledge-class one when the caller's org has no matching App install — validateChatScopeInvariants accepts both, so a client must not assume the memory class from the scope.

Value Description
private
shared

ChatToolChoice

4005: how a chat turn offers its respond tool.

Value Description
AUTO tool_choice auto: for the models that reject a forced choice. The turn also tells the model to answer by calling respond.
FORCED A forced choice of the respond tool: every other provider/model.

CommentAuthorKind

1606 — who a comment is from (hrn:node:hadronmemory.com:specs:cor:dmo:110:03).

Value Description
WORKER A named worker wrote it; the user who bound the session is provenance only.
USER A user wrote it directly.
USER_AGENT An unnamed agent wrote it on a user's behalf (a token or a run).
APP An App key with no user.

CommentThreadState

1606 — a comment thread's state (hrn:node:hadronmemory.com:specs:cor:dmo:110:05). Top-level comments only.

Value Description
OPEN
RESOLVED

ConnectionFlowStatus

Where a connect flow is (#2913).

Value Description
PENDING The flow has not completed. An answer, never an error.
CONNECTED The flow made, or reconnected, the connection in connectionId.
FAILED The flow ended without a connection; failureCode says why.

ConnectionProvider

The provider a connection is made to: a Microsoft 365 mailbox, a Gmail mailbox, a Google Calendar or a Google Drive. Each is its own OAuth client and its own capability tool.

Value Description
MS_EXCHANGE
GMAIL
GOOGLE_CAL
GOOGLE_DRIVE

ContentValidator

Value Description
AGENT
PLATFORM

CorpusState

1447 — a spec corpus's state, derived from its nodes since #1591: DRAFT while no live node is minted, MINTED once any is.

Value Description
DRAFT
MINTED

CreateUserPermission

Value Description
DENY
EXPLICIT
IMPLICIT

DashboardWidgetType

772 — the kinds of widget placeable on a user's /app/dashboard grid.

Value Description
MEMORY_STATS { memoryCount } — how many memories the caller OWNS: the memories(filter: { ownedByMe: true }) slice, not everything they can read (#1231). Stated here because the population is the contract: a client that has to guess it writes its own count, and then the two disagree.
AGENT_STATS { agentCount } — how many agents the caller OWNS: the agents(filter: { ownedByMe: true }) slice (#1231). Owner-scoped for every caller, platform admins included.
USAGE_ACTIVITY { windowDays, buckets } — the caller's usage activity over a rolling window.

DecisionAnswerVia

1641 — where an answer was given, as the answering caller states it (a claim).

Value Description
PORTAL
CLI
MCP
CHAT_RECORDED
IMPORT

DecisionSort

1641 — list order. PORTAL_DEFAULT: urgent first, then open before answered, then newest ask. CODE: code order.

Value Description
PORTAL_DEFAULT
CODE

DecisionState

1641 — a decision's derived state (hrn:node:hadronmemory.com:hadron-server:design:decision-nodes §6.3). Computed by the one evaluation on every read, never stored. Precedence: TAMPERED, UNVERIFIABLE, WITHDRAWN, SUPERSEDED, STALE, DECIDED, ANSWERED_UNCONFIRMED, OPEN.

Value Description
OPEN Not every part is answered.
ANSWERED_UNCONFIRMED Every part is answered; the tier's evidence (a decider's approval, or later a signature) is missing at the current revision.
DECIDED Answered, and the tier's evidence by a decider is intact at the current revision. The only state a ruling may be relied on in.
STALE Evidence exists, but for an earlier revision: the decision changed after it was approved.
TAMPERED The rendered content, the structured payload and the approval hash disagree: changed outside the decision operations.
UNVERIFIABLE Written by a codec or renderer this server does not know, so it cannot be verified (fail closed).
WITHDRAWN
SUPERSEDED

DecisionTier

1641 — the assurance a decision's answer needs. APPROVED: a decider's approval. SIGNED: a decider's passkey signature (#1614; not available yet, so a SIGNED decision stays ANSWERED_UNCONFIRMED).

Value Description
APPROVED
SIGNED

DecisionUrgency

Value Description
NORMAL
URGENT

DesiredRunState

4224: whether a worker's agent process should be running.

Value Description
RUNNING
STOPPED

DesiredStateReason

4224 (S3 of #4229): why a worker's desired state is what it is. A closed set. The first three come from the

Agent's lifecycle. RETIRED, HALTED, PAUSED, TEAM_PAUSED and RESETTING always win over the lifecycle, in that order, and always read STOPPED. LEAVE_ALONE wins over all of those, and SWEEP_OFF over everything: with either, nothing is desired (desired is null) and wouldBe says what the state would otherwise be.

Value Description
LONG_LIVED A worker of a LONG_LIVED Agent: RUNNING.
HOLDS_TASK A worker of a SHORT_LIVED Agent that is the assignee of a pending or started task, including one waiting on its child tasks (the worker stays up and is woken by their events): RUNNING.
NO_OPEN_TASK A worker of a SHORT_LIVED Agent that is the assignee of no pending or started task: STOPPED.
RETIRED The worker is retired.
HALTED A live halt stop signal covers the worker (hrn:node:hadronmemory.com:specs:cor:agt:090:01).
PAUSED A live pause stop signal covers the worker (hrn:node:hadronmemory.com:specs:cor:agt:090:01). A pause-dispatch signal stops assignment only and is not a reason here.
TEAM_PAUSED The App is under a team pause (App.teamPausedAt).
RESETTING A context reset holds the worker (hrn:node:hadronmemory.com:specs:cor:agt:050:27): its host is relaunching it.
LEAVE_ALONE The worker is marked leave-alone (Worker.leaveAlone).
SWEEP_OFF The App's sweep mode is OFF.

DriveExportFormat

Text representation a drive export can request.

Value Description
MARKDOWN
TEXT
HTML

DriveFileKind

Provider-neutral file kind (native document types vs plain files).

Value Description
FOLDER
DOCUMENT
SPREADSHEET
PRESENTATION
FILE

DueWakeStatus

Value Description
OK
WAKE_BUDGET_EXHAUSTED The App's daily wake budget is spent; the withheld wakes stay due (hrn:node:hadronmemory.com:specs:cor:agt:080:15).

EdgeGovernedKind

Which server-owned mechanism governs an edge (#2124). A governed edge is written by its own path and refused by every ordinary edge write. A client must tolerate a value it does not know as read-only/unsupported, never as an ordinary edge: this list grows when the server adds a governed kind.

Value Description
INCLUDE Derived from an include tag in the source node's content (#2040).
COMMENT_ANCHOR A comment's anchor edge to the node it comments on.
COMMENT_REPLY A reply comment's edge to its thread root.

EffortLevel

4291 (hrn:node:hadronmemory.com:specs:cor:agt:060:04) — the generic effort scale of a run. LOW to MAX are levels the launcher maps to the

family's own values; UNSET is the family's default. NOT_APPLICABLE is report-only: a session whose family has no effort control reports it, and a worker's last-used record may hold it; a task never carries it. Self-declared, like the family and model: a reporting input, never authorization.

Value Description
LOW
MEDIUM
HIGH
XHIGH
MAX
UNSET
NOT_APPLICABLE

EmailFlag

Provider-neutral flag state (spec 002) — Graph's tri-state mapped to a neutral vocabulary so a future Gmail tool can map its own subset.

Value Description
FLAGGED
NONE
COMPLETE

EmbeddingSource

033-rag-vector-retrieval: what a memory's vector index is built from.

Value Description
abstract
contentChunks
both

FindNodesMode

Retrieval modes for findNodes (hrn:node:hadronmemory.com:specs:cor:api:090:01). keyword is stemmed FTS; vector/hybrid need the memory's vector index; regex is a POSIX pattern match. vector/hybrid offset pages are not snapshot-stable while the index fills; page with keyword over one memory when every match must appear exactly once (#2991).

Value Description
keyword
vector
hybrid
regex

GrantAnnouncement

1747 — whether the team-chat post for a grant use went out.

Value Description
POSTED
FAILED

GrantHolderKind

Which kind of party holds a grant (#3789): exactly one of the four, as stored.

Value Description
USER
AGENT
WORKER
APP

GrantSignatureState

3649 slice D (hrn:node:hadronmemory.com:specs:cor:acl:140:07; hrn:node:hadronmemory.com:specs:cor:dmo:130:04 mirrored) — a grant signature's state, derived on every read and never stored. A record that does not verify is never a signature: it is counted in GrantSignatureStatus.integrityProblems instead. This is the signature's state, not the grant's: whether the grant allows anything is Grant.allows.

Value Description
CURRENT Verifies, and was made over the grant's present record version and terms.
EARLIER Verifies, but the grant's record version or terms no longer match what was signed.
PENDING Made by a first passkey still in its cooling-off window (hrn:node:hadronmemory.com:specs:cor:aut:040:07); never counts until the window ends normally.
CANCELLED Made by a first passkey revoked inside its window; never counts.

GrantSigningRequestState

3649 slice B (hrn:node:hadronmemory.com:specs:cor:acl:140:07) — a grant signing request: open, then ends exactly once.

Value Description
OPEN
COMPLETED A signature was verified and recorded.
DECLINED The signer turned it down.
EXPIRED Its lifetime passed (SIGNING_REQUEST_TTL_SECONDS, default 24h); endedAt is the deadline.
STALE The grant was revoked, its holder went, or its version or terms moved (a user merge moving the holder among them).
WITHDRAWN The requester account withdrew it.

GrantState

4173 (hrn:node:hadronmemory.com:specs:cor:acl:140:03): where a grant stands, worked out from its record on every read and never stored. An

ended grant keeps its first end. A grant withdrawn before #4173 shipped reads REVOKED (its withdrawal was not recorded separately). No name exists yet for an end from a deleted secret or from protection being turned on.

Value Description
PENDING Asked for and not yet signed. Allows nothing.
ACTIVE Signed and not ended. Allows its action once its start has come (allows says whether that is now).
SPENT Its use limit was reached.
EXPIRED Its expiry came first (a pending grant past its expiry too).
REVOKED Ended by a person's revoke.
WITHDRAWN Its pending request was withdrawn.
HOLDER_GONE The holder went (a person erased, a worker retired, an agent or App deleted).

HostOperationIssuer

1709 — who issued a host operation.

Value Description
USER
WORKER
PLATFORM

HostOperationOutcome

1709 — a host's report: done, or failed with a reason.

Value Description
SUCCEEDED
FAILED

HostOperationStatus

1709 — a host operation's status (hrn:node:hadronmemory.com:specs:cor:agt:070:02; COLLECTED is #1709's, Proposed).

Value Description
ISSUED
COLLECTED
SUCCEEDED
FAILED

HostSetupSource

4222 — who states which workers a host runs (hrn:node:hadronmemory.com:specs:cor:agt:070:01, the change Proposed). HOST: the host, at registration (the default, as before). SERVER: the platform's assignments; a registration is checked against them and a start uses them.

Value Description
HOST
SERVER

IdentifyUserMethod

Value Description
USER_ID
SECRET

ImportNodeStatus

importNode outcome. Sync v1 always returns STORED with the stored node; FETCH_PENDING + jobId are RESERVED for the future async url path (same API shape, no breaking change when it lands).

Value Description
STORED
FETCH_PENDING

InstallMethod

3435 — how an App installs an Agent: by an AppAgent row, or derived from a direct import of an installed Agent.

Value Description
ROW
DERIVED

LintKind

2048 (hrn:node:hadronmemory.com:specs:cor:agt:040:13) — what link lint warns about.

Value Description
RECOMPILE_AVAILABLE A recompile would select a newer revision; shown only to a compiler, without hidden target details.
POLICY_OVERRIDE An install-memory node replaces an Agent node.
RETIRED_TARGET The include's target is soft-deleted (hrn:node:hadronmemory.com:specs:cor:agt:040:13, R20 A).
NO_QUALIFYING_REVISION The target is readable but has no revision that meets the include's settings (approved and/or rev=N).
PINNED_NEWER_APPROVED The include pins a revision and a newer revision is approved.
SIGNING_NOT_CHECKED The include says signed; this deployment's signing policy is off, so signing is not checked.
BROKEN_INCLUDE The target is missing or the caller cannot read it. Position only: it never says which, or anything about the target.
WORKER_LINK_MISSING A worker's signature or trailer does not carry the worker link (hrn:node:hadronmemory.com:specs:cor:agt:040:04 S3). workerField names which.

MemoryClass

Value Description
system
app
knowledge
personal
group 023-app-shape US4: team-shared memory with symmetric membership. Governed by a list of MemoryMember rows (each with reader/writer/ owner role) — no single owner field on Memory. Closes the Company Brain gap that wasn't covered by the four legacy classes.
private Single-owner, owner-only memory — no MemoryShare path (not shareable), no ADMIN/OWNER bypass. Spec 034 (hadron-server #242) made it user-creatable via createMemory: free-standing (no app/agent) or app-scoped. May opt into encrypt-at-rest (the private CLASS marks it; visibility is NULL), but the encryption implementation itself is a deferred follow-up — do NOT rely on at-rest encryption for secret material yet.

MemoryConfigApplyOutcome

1334 — what applying a template did (or, on a dry run, would do) for one role.

Value Description
APPLIED The memory had no rule for the role; the template's was copied in (locked if the template is required).
SKIPPED_CONFLICT The memory already had a rule for the role, and a non-required template never overrides one.
REPLACED The memory's rule for the role was overwritten by a required template's, and is now locked.
SKIPPED_LOCKED A required template met a LOCKED rule that you have no authority to move; the rule stands.

MemoryConfigTemplateOwnerType

1325 part (c) — which entity owns a MemoryConfigTemplate. Exactly one per template.

Value Description
HADRON_SERVER
ORGANIZATION
USER
APP

MemoryMemberRole

023-app-shape US4: role on a MemoryMember row. Symmetric team membership for group-class memory. - reader: read access. - writer: read + write (the member can add/edit/delete nodes within the memory). - owner: read + write + management — add/remove other members, change roles, delete the Memory itself. Subject to the last-owner protection rule (FR-038): the platform refuses to remove or demote the sole remaining owner; the path to fully empty a group memory is to delete it.

Value Description
reader
writer
owner

MemoryShareRole

023-app-shape US3: role on a MemoryShare row. Asymmetric grant for personal-class memory. - reader: read access only. - writer: read + write (the grantee can add/edit/delete nodes within the memory).

Value Description
reader
writer

MemoryTransferHandling

Value Description
CARRY
REFUSE
REMOVE
CREATE

MemoryValidationCheck

One health check the validator runs (#819).

Value Description
BROKEN_REF An edge whose target node is missing OR soft-deleted. A hard-deleted target cannot occur - Edge.target is FK-enforced with onDelete: Cascade - so in practice this means a dangling edge to a tombstone.
SPARSE A non-object node with no description, content, or abstract. Object nodes (objectType set) are data-only by design and never sparse (#2516).
STALE_ABSTRACT The abstract no longer reflects current content (spec 032 FR-011).
EMBED_FAILED embedding_failed_at is set - a retryable failure awaiting its backoff, or the permanent class (deterministic 4xx, dimension mismatch, #206 encrypted-no-plaintext) recoverable via retryFailedEmbeddings (spec 033 / #882). Such a node is absent from vector search, which from outside looks identical to no hits matching.
INDEX_TRUNCATED Informational: passage indexing succeeded with later chunks omitted by the cap; does not make ok false.
GIT_MIRROR_FAILED A Git-mirror attempt for this node did not land (#430): a fixed failure class and an attempt count, never exception text. The repository may be stale until the next successful mirror, and a repo-wins sync can revert the lost write. Recorded for failures the process survives; a crash before the record, or a lost event, leaves no row.
SCHEMA objectType/properties violate the memory declared schema (#725).

MemoryVisibility

035-visibility-enum-cleanup: meaningful only for knowledge (PUBLIC/ORGANIZATION) and group (GROUP); null otherwise. PERSONAL/PRIVATE were dropped — privacy is the personal/private memory CLASS now.

Value Description
PUBLIC
ORGANIZATION
GROUP 023-app-shape US4: team-shared visibility. Bound bidirectionally to MemoryClass.group by the chk_memory_group_visibility CHECK constraint — a memory has class=group iff visibility=GROUP.

MentionWake

1747 — whether a mention wakes a worker at once. There is no ON_TICK mode.

Value Description
IMMEDIATE
OFF

ModelGroupOrigin

Where an effective model group comes from.

Value Description
AGENT Declared by the App's Team Agent, with no App override.
APP_OVERRIDE The App replaced the Agent's group of this name.
APP The App's own group; the Agent declares none of this name.

NodeApprovalState

1591 — whether a node's approval still covers its current text (#1611: title, abstract and content under approval-hash v1; a metadata-only revision keeps it).

Value Description
NOT_APPLICABLE Approval is not applicable in an encrypted memory.
NOT_APPROVED Never approved.
APPROVED The approval covers the current text: it was recorded at the revision in NodeApproval.revision, which can be older than Node.revision when only metadata (tags, properties, role, description, alias, loc, edges) changed since.
SUPERSEDED Approved once, then the title, abstract or content changed (or the text no longer hashes to the approval, see verifyNode's TAMPERED).

NodeAuthorshipKind

Value Description
TASK
HUMAN

NodeContentScope

1608 — which kinds of node a search or list returns (hrn:node:hadronmemory.com:specs:cor:dmo:110:08).

Value Description
CONTENT Content only, never comments. The default.
COMMENTS Comments only, never content: feedback, not verified fact about its target.
ALL Content and comments; every comment hit is still a comment (see Node.asComment).

NodeContentValidationAuthorCheck

1332 (hrn:node:hadronmemory.com:specs:cor:dmo:160:01) — CHECKED: R's recorded author was compared with the reporter and differs, never a claim of independence. AUTHOR_UNKNOWN: there was nothing recorded to compare.

Value Description
CHECKED
AUTHOR_UNKNOWN

NodeContentValidationOutcome

Value Description
PASS
FAIL
ERROR

NodeContentValidationState

Value Description
UNVALIDATED
STALE
PASS
FAIL
ERROR

NodeExportEncoding

How the rendered payload is encoded. TEXT for MD/JSON; BASE64 for PDF.

Value Description
TEXT
BASE64

NodeExportFormat

Single-node export (#386). MD/JSON are the canonical, round-trippable files; PDF is a presentation render (content only) produced by the internal hadrontool-pdf service and delivered BASE64. HTML remains reserved.

Value Description
MD
JSON
PDF

NodeExportSection

Selectable sections for a presentation (full: false) export.

Value Description
METADATA
CONTENT
ABSTRACT
DATA
PROPERTIES
EDGES

NodeField

Node fields a lexical (keyword/regex) query matches and weights. Weight-mask, NOT a hard filter: naming a subset zeroes the excluded fields in scoring but does not strictly exclude them from matching (cor:api:090:03). Ignored by mode:vector (the index source is a per-memory config, not a query param).

Value Description
name
alias
loc
tags
description
abstract
content
properties
data

NodeIntegrityState

1591 — the tamper check's verdict.

Value Description
INTACT The current revision is approved and its text still hashes to the approval.
TAMPERED Approved text no longer hashes to its approval: it changed outside the revision system.
SUPERSEDED Edited (a new revision) since the last approval. Not a tamper finding.
NOT_APPROVED Never approved: nothing to verify against.

NodeMergeField

A node field that mergeNodes can fold from the source into the target.

Value Description
CONTENT Concatenate source content after target content (blank-line separated).
ABSTRACT Concatenate source abstract after target abstract (2000-char cap enforced).
DESCRIPTION Concatenate source description after target description.
TAGS Union the tag sets (target order first, then new source tags).
DATA Shallow-merge the encrypted 'data' JSON; target wins on key collisions.
PROPERTIES Shallow-merge the 'properties' JSON; target wins on key collisions.
EDGES Re-point the source's incoming and outgoing edges onto the target. Each re-homed edge's loc is recomputed from its new endpoints (deriveEdgeLoc); a re-homed edge whose recomputed (loc, memoryId) collides with one the target already holds is dropped rather than duplicated — so an equivalent edge with an endpoint-derived loc is de-duplicated — as are self-loops.

NodeMoveLinkStatus

Value Description
MISSING
RETARGETED
AMBIGUOUS

NodeRoleRuleRefState

1325 — the state of one rule reference, next to its URN and id. NONE: not

configured. OK: the node is live and you can read it; its id is given, and its URN too unless the node's memory has a legacy URN that cannot address it (#697), when the URN is null and the id is the ref to use. BROKEN: configured, but its node or memory is gone, so operations relying on a procedural rule are refused until a manager repoints it (fail-closed). Missing description documentation instead reports NONE through descriptionNodeState. UNREADABLE: the node exists but you may not read it, so its URN and id are withheld.

Value Description
NONE
OK
BROKEN
UNREADABLE

NodeRoleWriters

1331 — who may write a node whose role this rule governs, ON TOP OF memory write access (never instead of it).

A write is judged against the role the node has BEFORE it and the role it has AFTER, so creating, editing, changing or clearing a role all need the level.

Value Description
ALL Anyone who may write the memory. Grants no new access.
OWNER NOT BUILT yet (#1333): any write touching this role is refused (ROLE_WRITERS_UNSUPPORTED). Never read as ALL.
ADMIN The owning organization's ADMINs and OWNERs, and the owning user (ROLE_WRITER_LEVEL_REQUIRED otherwise).

NodeSort

Result ordering for findNodes. Default relevance; the rest suppress scoring (browse order).

Value Description
relevance
loc
seq
updatedAt

NodeTextField

Text-bearing Node fields that searchReplaceInNodes may rewrite. JSON fields (data, properties) and the structural 'loc' are intentionally excluded in v1.

Value Description
content
name
alias
description
abstract
tags

NodeValidationTaskSetState

3659 (hrn:node:hadronmemory.com:specs:cor:dmo:160:01) — READY: a report may name any listed task at revisions 1 to its revision. NOT_CONFIGURED: no rule applies. BROKEN: a rule's task reference is broken, so every report is refused, including one naming a listed task. UNAVAILABLE: the caller does not write the memory, or cannot read a task a rule names (ruling 0199); nothing is listed.

Value Description
READY
NOT_CONFIGURED
BROKEN
UNAVAILABLE

NodeWhereCast

How a NodeWhere leaf's extracted value is typed before comparison (#719). Default text.

Value Description
text
number
datetime
boolean

NodeWhereColumn

JSONB column a NodeWhere leaf reads (#719). Defaults to properties.

Value Description
properties
data

PrincipalType

The kind of principal a credential resolved to (issue #562). USER covers both JWT sessions and hdr_user_ personal API keys; APP is an hdr_app_ key. AGENT is reserved for a future agent-credential principal — no auth path produces it today.

Value Description
USER
APP
AGENT

RateLimitEnforcementMode

Per-class deployment rollout. LOG_ONLY counts without limiter refusal.

Value Description
LOG_ONLY
ENFORCING

RateLimitFieldClass

Server-owned request cost class (#1793); not a client branching contract.

Value Description
CREDENTIALS
OUTBOUND
WRITES
FAN_OUT_READS
OTHER_READS

ReadyFilter

3125 S3: the caller's ready filter against the integration's readyLabel (ANY by default). ONLY on an integration with no readyLabel lists nothing.

Value Description
ONLY
EXCLUDE
ANY

RegisterDisclosure

S5 — why an attendee cannot act on a register row. Rendered identically by every consumer.

Value Description
HOST_MEMORY_NOT_READABLE
HOST_MEMORY_NOT_WRITABLE
CHANNEL_DELETED
DRIVER_NOT_PARTICIPANT
UNKNOWN_ACTOR
IMPERSONATION

RegisterNamedBy

Which attendee column the winning register row named.

Value Description
WORKER
AGENT
EVERYONE

RegisterOwnerType

A register row is owned by exactly one of the two; Agent-owned rows do not exist (plan §14).

Value Description
ORGANIZATION
APP

RegisterRole

What a register row declares: INTENT, never permission (D-2026-09-13-008).

Value Description
WATCH
POST
BOTH

RegisterRouteKind

Value Description
WORKER
USER

ResumeOutcome

1956 (hrn:node:hadronmemory.com:specs:cor:agt:020:03) — what resumeSession did. RESUMED: bound to an open

session (a shed's claim, or the one live session of the fast path). STARTED: the claimed session had ended (a rotation), so the worker's next session was started. CHOOSE: several candidates, nothing bound or consumed; call again with session set to the one the human picks.

Value Description
RESUMED
STARTED
CHOOSE

ResumeSource

1956 — where a resume candidate came from: an unused resume claim, or (with no claim) a live bound session.

Value Description
CLAIM
LIVE_SESSION

ReviewVerdict

3448 — a typed review outcome; the command records it without finishing the task (hrn:node:hadronmemory.com:specs:cor:agt:050:08).

Value Description
APPROVE
CHANGES_REQUESTED
PASS
FAIL
CARRY
REFUSED

Role

Value Description
OWNER
ADMIN
CONTRIBUTOR
READER

ScopeOwnerType

Which entity owns a Scope. Exactly one per scope (DB-enforced, the AiServiceConfig pattern).

Value Description
ORGANIZATION
AGENT
APP

SearchEntityType

Entity types the cross-entity global search (globalSearch) can return. Mirrors the SearchEntityType union in src/lib/global-search.

Value Description
organization
memory
node
agent
app
aiServiceConfig
user
agentTask GraphQL only (hrn:node:hadronmemory.com:specs:cor:api:050): MCP hadron_search stays at seven types. Hits only for a person or worker session the task read gate admits.

SearchField

Fields globalSearch can match against. Omit fields to let the server smart-sniff the query shape (PK → URN → name); explicit fields override the sniff. pk is exact-match; the rest are case-insensitive substring. content (node bodies) is opt-in and skips encrypted memories.

Value Description
urn
name
description
pk
content

SearchGranularity

Result granularity for findNodes (cor:api:090). Spec 033.

  • node: one entry per matching node (default).
  • chunk: passage-level entries with offsets into the parent node's content (vector mode only; chunk hits collapse to node-level when granularity is node).
Value Description
node
chunk

SearchReplaceSkipReason

Value Description
OTHER_GOVERNED_KIND
PROTECTED_ADDRESS

ServedPromptKind

The kind of served prompt: bind, chat, or run.

Value Description
BIND
CHAT
RUN

ServedPromptPointerLevel

Value Description
WORKER
APP_AGENT
AGENT

SessionEndReason

1156 — hrn:node:hadronmemory.com:specs:cor:dmo:070:05: closed end causes; unknown is reserved for legacy rows.

Value Description
ended
superseded
expired
agent_absent #4292: the host running a SHORT_LIVED worker ended the session on its proof that no agent runs; no handoff was written.
unknown

SessionState

2288: derived per-session state; ENDED means terminal, not necessarily an explicit end.

Value Description
LIVE
LAPSED
DORMANT
ENDED

SignatureState

1632 (hrn:node:hadronmemory.com:specs:cor:dmo:130:04) — a signature's state, derived on every read. An invalid record is never a signature: it is counted in NodeSignatureStatus.integrityProblems instead.

Value Description
CURRENT Verifies, and the title/abstract/content has not changed since it was made.
EARLIER Verifies, but the content changed since; restoring the old text never makes it current again.
PENDING Made by a first passkey still in its cooling-off window; never counts until the window ends normally.
CANCELLED Made by a first passkey revoked inside its window; never counts.
NOT_APPLICABLE The node is in an encrypted memory, where signing does not apply.
ENDED_ENCRYPTED_MEMORY The node left an encrypted memory it carried this signature into; never counts again. (Derivation lands with E2.)

SigningRequestState

1632 (hrn:node:hadronmemory.com:specs:cor:dmo:130:03) — a signing request: open, then ends exactly once.

Value Description
OPEN
COMPLETED A signature was verified and recorded.
DECLINED The eligible signer turned it down.
EXPIRED Its lifetime passed (SIGNING_REQUEST_TTL_SECONDS, default 24h); endedAt is the deadline.
STALE The node's title, abstract or content changed, or it entered an encrypted memory.
WITHDRAWN The requester account withdrew it.

SkillExportAction

A client-side filesystem action planned by the server. It does not claim that I/O occurred.

Value Description
WRITE
MOVE
REMOVE
SKIP
REFUSE
FAIL

SkillPlanIntent

What the caller intends to do with the plan. It decides the ACTION, never the class.

Value Description
LINT Corpus judgment only: findings, no files consulted, no bodies returned.
STATUS Classes and findings for files the client found. Never returns a body.
EXPORT Classes, findings, and the rendered body for anything the client should write.

SortDirection

Sort direction for a findNodes property-path sort (#719). Default asc.

Value Description
asc
desc

SpecMintFindingKind

1448 — why the mint report lists an item.

Value Description
PLACEHOLDER A reserved citation with no spec written yet.
UNRESOLVED_REFERENCE A reference to a spec that does not exist, or to a placeholder (rule: MISSING | PLACEHOLDER).
LINT A structural lint error (rule: nodetype-info | tag-spec | serialization-leak | duplicate-loc).
STALE_ABSTRACT An abstract written for an earlier body.
NOT_APPROVED #1591 — the node's current revision is not approved.
TAMPERED #1591 — the approved revision's text changed outside the revision system, so it no longer matches its approval hash. Re-approve it.
CITES_UNMINTED #1591 — an edge, live pending edge or text citation (a prefixed node URN) into another memory's node that is not minted yet (targetLoc is its URN).

SpecReferenceKind

1449 — how a spec corpus reference was found.

Value Description
URN A node URN in the corpus text (name, description, abstract or content), including inside a URL.
EDGE A real edge from a corpus node.

SpecReferenceProblem

1449 — why a reference does not reach a written spec.

Value Description
MISSING No live node at the cited loc.
PLACEHOLDER The cited node is a placeholder: a reserved citation with no spec written yet.

SpecRewriteStatus

1449 — state of one node's reference rewrite in a renumber.

Value Description
PLANNED Dry run: this rewrite would be made.
REWRITTEN
UNCHANGED A concurrent edit removed the references (or the node) before the rewrite, so nothing was written.
FAILED The rewrite was refused or kept conflicting; error says why. The move itself stands.

SpecTextField

Only text fields a spec bulk edit may change.

Value Description
content
abstract

StopNoticeKind

2022 — whether a stop notice tells the worker to stop or that it may resume.

Value Description
STOP
RESUME

StopSignalEndKind

Value Description
LIFTED
EXPIRED

StopSignalLevel

2022 (hrn:node:hadronmemory.com:specs:cor:agt:090:01) — a stop signal's level. Each stops everything the one before it does.

Value Description
PAUSE_DISPATCH Stops assignment only: matching skips the covered workers and a manual assignment to one is refused (TASK_STOPPED). Its coordinators are told, by a consumer that has declared their lane (a set is refused until one has).
PAUSE Also stops ticks and stall time. Each covered worker is told to finish or stop at its next sub-task, by a consumer that has declared its lane (a set is refused until one has).
HALT Also tells each covered worker to save its work and write a hand-off now. The notice is typed as an ordinary message into a verified-empty input, with no interrupt key (Holger, option A, 2026-10-24); one that cannot be typed is logged and flagged to the coordinator.

StopSignalScope

2022 — a stop signal's scope: one worker, a team (its head and the whole reporting tree under it), or the workers a host registration lists.

Value Description
WORKER
TEAM
HOST

SubscriptionType

Value Description
READ_ONLY
READ_WRITE

SweepMode

4224 (S3 of #4229): the App's sweep switch.

Value Description
OFF The sweep acts on no worker: every hostDesiredState row says SWEEP_OFF. The default.
OBSERVE The sweep compares desired state with what it sees and reports; it repairs nothing.
APPLY The sweep also repairs what it can.

SweepRunOutcome

4233: what a sweep did to one worker in one run.

Value Description
APPLIED
SKIPPED
FAILED

SyncStatus

Value Description
PENDING
SYNCING
OK
ERROR

TaskWakeEvent

1708 — which task event a TASK reason is for.

Value Description
ASSIGNED
REASSIGNED
MATCHED The platform's matcher assigned it (hrn:node:hadronmemory.com:specs:cor:agt:060:06).
CHILD_FINISHED A child task finished; the reason names the child. Due to the child's owner (hrn:node:hadronmemory.com:specs:cor:agt:050:16) and, #4234, to the parent's current assignee.
CHILD_CANCELLED #4234 — a child task was cancelled; the reason names the child. Due to the same two as CHILD_FINISHED (hrn:node:hadronmemory.com:specs:cor:agt:050:16).
ALARM An unacknowledged alarm's currently-woken chain position (hrn:node:hadronmemory.com:specs:cor:agt:050:19). Delivering it never acknowledges the alarm.
END_SESSION #1709 — the task was cancelled and asks its assignee to end its session (hrn:node:hadronmemory.com:specs:cor:agt:050:10). Due while that session is open and the platform has not yet ended it through a host.

TeamRosterState

1707 — a worker's derived state on the team roster (plan

design:agent-tasks §7.4). Plan-derived, not a spec. A worker can be in several at once; it is shown in the first that holds, in this order.

Value Description
YOUR_MOVE Woken on an unacknowledged alarm (hrn:node:hadronmemory.com:specs:cor:agt:050:19), or a child task it owns finished or was cancelled after it last acted (hrn:node:hadronmemory.com:specs:cor:agt:050:16).
UNAVAILABLE Its own availability record, or every model family it can run as, says unavailable now (hrn:node:hadronmemory.com:specs:cor:agt:060:01); a stall mark included (hrn:node:hadronmemory.com:specs:cor:agt:060:07).
WAITING The assignee of a started task with open children (hrn:node:hadronmemory.com:specs:cor:agt:050:04).
WORKING The assignee of a started task.
ASSIGNED_NOT_STARTED The assignee of a pending task.
AVAILABLE Free for work (hrn:node:hadronmemory.com:specs:cor:agt:060:05), including an unbound worker a live host can launch, which the matcher assigns to, and a bound worker whose session is open but quiet, which the matcher also assigns to, reaching it through that session (see liveSession).
NO_FAMILY Bound, but its session reported no model family, so it can't be matched until one is given (hrn:node:hadronmemory.com:specs:cor:agt:060:04).
NOT_LAUNCHABLE Unbound, and no live host registration lists it.

TeamSpecForm

Value Description
SERVER
CLIENT_INPUT

TickActionState

What the register says this tick asks of the woken worker, as far as the reader may read (hrn:node:hadronmemory.com:specs:cor:agt:110:03).

Value Description
MAPPED A readable entry and runnable task.
UNMAPPED No mapping in the fully readable Team Agent chain, or no single Team Agent.
UNRESOLVED The readable entry's loc has no usable task in the lookup chain.
WITHHELD Code-only guidance: resolve the task yourself. Includes failed reads.

TickerReason

2068 (hrn:node:hadronmemory.com:specs:cor:agt:080:01, :10) — why a ticker fires. A closed set; several fire it when any one holds.

Value Description
READ_TEAM_CHANNEL Fires only when the subscriber has relevant unread in the ticker's channels (what relevance counts is the ticker's relevance).
EVERY_TICK Fires on every tick, with or without unread. The floor, budget, pause and dormancy still apply.
LIVE_CHECK #2138: fires when the subscriber has not checked its team channel within the ticker's cadence, whatever is unread, and never for a worker not expected to check (no task, paused, or a team pause).

TickerRelevance

1747 — how a ticker relevance narrows what can make a subscriber due (hrn:node:hadronmemory.com:specs:cor:agt:080:01).

Value Description
ALL
MENTIONS

TickerSubscriptionEndReason

1747 — why a subscription ended. Never dormancy.

Value Description
UNSUBSCRIBED
WORKER_RETIRED
TICKER_DELETED

UploadIntent

Value Description
USER
AGENT_REQUEST

UsageActivityBucketSize

Bucket width for usageActivity (#796).

Value Description
DAY
WEEK
MONTH

WakeKind

Value Description
MENTION
TICK
TASK #1708 — a task event the worker must act on (an assignment, a child's finish, an alarm's woken position, #1709 a request to end its session). Wakes at once, like a mention.
STOP #2022 — a stop-signal notice (hrn:node:hadronmemory.com:specs:cor:agt:090:04): ahead of everything else, past the floor, the busy delay and the budget's refusal. Offered only to a dueWakes call that lists STOP in accepts (#2169).

WorkerCheckState

2138 §3.4 (experimental) — a worker's check status. Draft spec: hrn:node:hadronmemory.com:hadron-dev-team-vera:work:2138-experiment-spec.

Value Description
NO_SESSION No live session; noSessionReason says why.
PENDING Not expected to check now; pendingReason says why.
OK Has a task and checked within failedChecksToOverdue × checkPeriodSeconds + 5 minutes.
OVERDUE Has a task and hasn't checked for longer than that. Long turns show here on purpose.

WorkerContinuityStatus

1029. MISSING is deliberately not "no handoff": it means the PREVIOUS stint

did not write one, while handoff may still carry an older record. Silently presenting a stale handoff as current is the failure this distinction exists to prevent.

Value Description
FIRST_STINT No previous ended session — nothing to inherit, and that is not a gap.
CURRENT The previous session wrote the handoff returned here.
MISSING The previous session ended, or was auto-expired, without writing one.

WorkerNoSessionReason

3077 — why a worker is NO_SESSION (hrn:node:hadronmemory.com:specs:cor:agt:100:03; idle versus ended per

hrn:node:hadronmemory.com:specs:cor:agt:020:03). A closed set: it carries no session id or timestamp.

Value Description
IDLE An open session would bind it, but nobody drove it inside its idle window.
ENDED Every session it had is over: ended, auto-expired, or past its promised expiresAt.
NEVER_BOUND It has never had a session. Deleted sessions count for nothing.

WorkerPendingReason

2138 §3.4 — why a worker is PENDING. Precedence: TEAM_PAUSED, STOPPED, PAUSED, NO_TASK.

Value Description
TEAM_PAUSED A team pause is in force (App.teamPausedAt); the worker can't lift it.
STOPPED #2022: a PAUSE or HALT stop signal covers the worker, so it is not ticked (hrn:node:hadronmemory.com:specs:cor:agt:090:03).
PAUSED Its own pause (pausedUntil) is in force.
NO_TASK No open task assigned, and its Agent uses tasks.

WorkerTeamPlacement

Value Description
UNSET
NO_TEAM
REPORTS_TO

WorkerTerminalPrompt

2771 — what the terminal's input prompt looked like.

Value Description
empty
not_empty
menu
unknown

WorkerTerminalReason

2771 — why a terminal is locked or dark: a closed code (hadron-cli#1187), never text from the screen.

Value Description
model_at_capacity
token_budget_exhausted
rate_limited
guardrail_triggered
menu_or_question
shed_staged_not_relaunched
unrecognized
no_turn_for_due_ticker
no_terminal
bare_shell
no_agent

WorkerTerminalRepair

4041 (V82, hrn:node:hadronmemory.com:hadron-dev-team-shared:decisions:2026-11-12-vera-rulings-host-repair-notice;

hrn:node:hadronmemory.com:specs:cor:agt:070:01) — what a host's sweep did about a dark worker. A closed set, never free text. The PLATFORM posts the notice, never the host key.

Value Description
RELAUNCHED The host relaunched the worker; carries attempt.
NO_SNAPSHOT The worker has no launch snapshot, so the host could not relaunch it.
CAP_REACHED The host's relaunch attempt cap was reached.
RELAUNCH_REFUSED #4247 — the host did not relaunch the worker because a safety check declined it. Carries repairReason from the refusal set (IDENTITY_MISMATCH, DUPLICATE_AGENT, PAUSED, HALTED, LEAVE_ALONE, NO_LAUNCHER_PROFILE) and attempt.
RELAUNCH_FAILED #4247 — the host tried to relaunch the worker and it did not come up. Carries repairReason from the failure set (LAUNCH_EXIT_NONZERO, TERMINAL_CREATE_REFUSED, TIMEOUT, SETUP_FAILED, VERIFY_FAILED) and attempt.

WorkerTerminalRepairReason

4247 — why a relaunch was refused or failed. A closed set, never free text. The first six go with RELAUNCH_REFUSED,

the last five with RELAUNCH_FAILED; a reason from the other set is refused (REPAIR_REASON_INVALID).

Value Description
IDENTITY_MISMATCH The worker's identity does not match its launch snapshot.
DUPLICATE_AGENT Another agent is already running in the worker's place.
PAUSED The worker is paused.
HALTED The worker is halted.
LEAVE_ALONE The worker is marked leave-alone.
NO_LAUNCHER_PROFILE The worker has no launcher profile.
LAUNCH_EXIT_NONZERO The launcher exited non-zero.
TERMINAL_CREATE_REFUSED Orca refused to create the terminal.
TIMEOUT The relaunch timed out.
SETUP_FAILED #4259 — the host could not prepare the launch (a setup or disk error); the launcher never ran.
VERIFY_FAILED #4259 — the launcher ran, but the host could not prove the agent came up.

WorkerTerminalState

2771 — what a host's sweep saw in a worker's terminal.

Value Description
busy
idle
locked
dark

Scalars

Boolean

The Boolean scalar type represents true or false.

DateTime

A timestamp string, e.g. '2026-07-30T12:34:56.789Z'.

Guaranteed parseable by Date.parse / new Date(). Values Hadron mints are ISO 8601 UTC; a value passed through from an external provider (calendar, mail, drive) keeps that provider's representation, which may carry a non-UTC offset — so compare instants, don't compare these as strings.

Issue #205: date fields used to be declared String and fed a Prisma Date, which graphql-js coerced through Date.valueOf() into epoch milliseconds ('1716943200000') — a value new Date() parses as Invalid Date. This scalar makes that shape unrepresentable, so no client needs to sniff the format.

Output-only today: date-valued arguments remain String.

Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

JSON

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.