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.
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: |
|
| 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: |
|
| 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: |
|
| 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: |
|
| 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 | ||
| 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 | ||
| 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 | ||
| 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! | ||
| String! | |||
| requestedFeatures | String | ||
| sendContactMessage | Boolean! | ||
| name | String! | ||
| 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 | ||
| 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! | ||
DefectLink¶
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 |
|
| 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:cor010: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: |
|
| 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 | ||
| 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 | ||
| 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 | |
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.