Documentation
¶
Overview ¶
Package work is the Go half of the work spine (design record docs/superpowers/specs/2026-09-05-work-spine-design.md, epic A2). It backs the seven builtins declared in dsl/work/builtins.memql:
integration.work.createGoal -- open a goal and its first run integration.work.cancelGoal -- ask every run of a goal to stop integration.work.forkRun -- derive a run that diverges at a step integration.work.replayRun -- derive a run served from the journal integration.work.decideApproval -- decide a human gate and resume integration.work.sweepWaiting -- resume due timers, close dead runs integration.work.retentionSweep -- archive then delete journal detail
THE DIVISION OF LABOUR IS THE DESIGN. Every DECISION is a pure function in component/work -- the symptom table, the replay verdict, the ceilings, the artifact-hash rule -- so the spec's headline claims are properties of values and are provable with no engine, no provider and no database. This package is only responsible for OBEYING those decisions and for the two things a pure package cannot do: reaching the engine, and getting the actor right (see store.go's header, which is the file to read before changing anything here).
Index ¶
- Constants
- Variables
- func AppDispatchSource(choice common.RouteChoice, owner string) string
- func CaptureSpine(name string) (*workflowhost.Snapshot, error)
- func GoalCallTags(goal map[string]any) []string
- func IsDriverOwnedRun(triggeredBy string) bool
- type ActRefusal
- type ApprovalSeed
- type Archiver
- type CompileRequest
- type Compiler
- type DirectGoal
- type DispatchRequest
- type Dispatcher
- type Engine
- type Integration
- func (i *Integration) ApprovalGuidanceAvailable(ctx context.Context, approval map[string]any) bool
- func (i *Integration) AskAboutFailedRemedy(ctx context.Context, ownerUserId, runId, stepKey, kind, reason string) error
- func (i *Integration) AskComputerScope(ctx context.Context, owner, runID string, subject map[string]any) (string, error)
- func (i *Integration) AskFeedback(ctx context.Context, owner, runID, question, kind string, ...) (string, error)
- func (i *Integration) AskFeedbackPresented(ctx context.Context, owner, runID, question, kind, presentation string, ...) (string, error)
- func (i *Integration) AskFeedbackWithPolicy(ctx context.Context, owner, runID, question, kind string, ...) (string, error)
- func (i *Integration) AskPlanReview(ctx context.Context, owner, runID string, subject map[string]any, ...) (string, error)
- func (i *Integration) CancelComputerUseRuns(ctx context.Context, ownerUserId string) (checked, asked int, err error)
- func (i *Integration) Capabilities() []memql.IntegrationCapability
- func (i *Integration) CheckExecutionDestination(ctx context.Context, runID, target string) error
- func (i *Integration) Claim(ctx context.Context, id string, req permission.Request, ...) (*permission.Scope, error)
- func (i *Integration) ContinueWorkProgress(ctx context.Context, rc common.RunContext, spent workstate.Spent, ...) (bool, error)
- func (i *Integration) DispatchRun(ctx context.Context, runId, ownerUserId string) bool
- func (i *Integration) EnableCompileViaEvent()
- func (i *Integration) FailRun(ctx context.Context, ownerUserId, runId, code, message string) error
- func (i *Integration) Find(ctx context.Context, req permission.Request) (*permission.Grant, error)
- func (i *Integration) HandleRunEvent(ev events.Event)
- func (i *Integration) HasLiveGoalForResponsibility(ctx context.Context, ownerUserId, responsibilityId string) (bool, error)
- func (i *Integration) HoldWorkRunLifecycle(ctx context.Context) (*memql.GateHold, error)
- func (i *Integration) InstallReplan(ctx context.Context, ownerUserId, runId string, t ReplanTemplate) error
- func (i *Integration) IntegrationName() string
- func (i *Integration) LimitReplyBudget(ctx context.Context, ownerUserId, runId string) error
- func (i *Integration) LimitWorkloadBudget(ctx context.Context, ownerUserId, runId, workload string) error
- func (i *Integration) LoadReplanContext(ctx context.Context, ownerUserId, runId, stepKey string) (ReplanContext, error)
- func (i *Integration) LockPlanReview(ctx context.Context, approvalID string) (func(), error)
- func (i *Integration) NewSink(opts SinkOptions) *Sink
- func (i *Integration) OpenAnalysisGoal(ctx context.Context, requestKey string, g DirectGoal) (ReviewGoalReceipt, error)
- func (i *Integration) OpenDirectGoal(ctx context.Context, g DirectGoal) (goalId, runId string, err error)
- func (i *Integration) OpenPipelineSecurityGoal(ctx context.Context, requestKey string, g DirectGoal) (ReviewGoalReceipt, error)
- func (i *Integration) OpenResponsibilityGoal(ctx context.Context, g ResponsibilityGoal) (string, string, error)
- func (i *Integration) OpenReviewGoal(ctx context.Context, requestKey string, g DirectGoal, subject map[string]any, ...) (ReviewGoalReceipt, error)
- func (i *Integration) PauseReplanForBudget(ctx context.Context, ownerUserId, runId, stepKey string, ...) error
- func (i *Integration) PauseWorkForBudget(ctx context.Context, ceiling *memql.RunCeilingError, checkpoint string) (string, error)
- func (i *Integration) PauseWorkForModelCall(ctx context.Context, failure, checkpoint, question string) (string, error)
- func (i *Integration) PrepareWorkTool(ctx context.Context) (bool, error)
- func (i *Integration) RaiseApproval(ctx context.Context, ownerUserId string, a ApprovalSeed) (string, error)
- func (i *Integration) RecordCompileOutcome(ctx context.Context, ownerUserId, runId string, fields map[string]any) error
- func (i *Integration) RecordToolInvocation(ctx context.Context, rec agentintegration.ToolInvocation) error
- func (i *Integration) RecoverableApprovalGuidance(ctx context.Context, approval map[string]any) string
- func (i *Integration) RequestRepair(ctx context.Context, ownerUserId, runId, stepKey, violation string) error
- func (i *Integration) RestoreInferenceWaits(ctx context.Context) (int, error)
- func (i *Integration) RetentionSweep(ctx context.Context, dryRun bool) (RetentionResult, error)
- func (i *Integration) RunBudget(ctx context.Context, ownerUserId, runId string) (work.Ceilings, error)
- func (i *Integration) ServeAnswerChecks(c RunClaimer)
- func (i *Integration) SetAppRecoveryPublisher(publish func(events.Event))
- func (i *Integration) SetArchiver(a Archiver)
- func (i *Integration) SetCompiler(c Compiler)
- func (i *Integration) SetDispatcher(d Dispatcher)
- func (i *Integration) SetGateDB(gate func() *sql.DB)
- func (i *Integration) SetNow(f func() time.Time)
- func (i *Integration) SetPlanReviewAnswerValidator(kind string, ...)
- func (i *Integration) SetPlanReviewValidator(kind string, validate func(context.Context, map[string]any) error)
- func (i *Integration) SetRemedy(r Remedy)
- func (i *Integration) SetRunClaimer(c RunClaimer)
- func (i *Integration) StepVersions(ctx context.Context, runId string) ([]map[string]any, error)
- func (i *Integration) SweepWaiting(ctx context.Context, olderThan time.Duration) (WaitSweepResult, error)
- type ModelJournal
- type OperationalRetentionResult
- type Remedy
- type ReplanContext
- type ReplanTemplate
- type ResponsibilityGoal
- type RetentionResult
- type ReviewGoalReceipt
- type RunCeilings
- func (c *RunCeilings) Admit(ctx context.Context, rc common.RunContext, estimatedTokens int) *memqlengine.RunCeilingBreach
- func (c *RunCeilings) AdmitProvider(ctx context.Context, rc common.RunContext, policy memql.ProviderAdmission) error
- func (c *RunCeilings) Charge(ctx context.Context, rc common.RunContext, spend memqlengine.ModelSpend)
- func (c *RunCeilings) Deadline(ctx context.Context, rc common.RunContext) (time.Time, error)
- func (c *RunCeilings) DeclaredDeadline(ctx context.Context, rc common.RunContext) (time.Time, error)
- func (c *RunCeilings) ModelCallBudget(ctx context.Context, rc common.RunContext) (limit, used int, err error)
- func (c *RunCeilings) Spent(_ context.Context, rc common.RunContext) memqlengine.RunSpend
- type RunClaimer
- type SessionWriter
- func (w *SessionWriter) CloseRecording(ctx context.Context, r workerservice.RecordingClose) error
- func (w *SessionWriter) HeartbeatRecording(ctx context.Context, r workerservice.RecordingHeartbeat) error
- func (w *SessionWriter) OpenRecording(ctx context.Context, r workerservice.RecordingOpen) (string, error)
- func (w *SessionWriter) RecordAction(ctx context.Context, r workerservice.RecordedAction) error
- func (w *SessionWriter) RecordGap(ctx context.Context, r workerservice.RecordedGap) error
- func (w *SessionWriter) SetNow(now func() time.Time)
- type Sink
- type SinkOptions
- type WaitSweepResult
Constants ¶
const ( RemedyReplan = waitKindReplan RemedyRepair = waitKindRepair )
RemedyReplan and RemedyRepair name the two remedies to the writes a remedy makes back through this package (AskAboutFailedRemedy): the wait kinds they serve, exported so the planner does not spell them a second time.
const ( // EnvModelCallRetentionDays and EnvObservationRetentionDays are the two // windows the design names. Observations are kept twice as long as model // calls because they are the EPISODIC MEMORY the recall builtin reads, // while a model call is evidence about one request. EnvModelCallRetentionDays = "MEMQL_WORK_MODELCALL_RETENTION_DAYS" EnvObservationRetentionDays = "MEMQL_WORK_OBSERVATION_RETENTION_DAYS" // EnvArchiveContainer is the blob container the retention sweep writes // to, falling back to the cluster's own container. Shared with the log // store's archive by design: one deployment, one archive. EnvArchiveContainer = "MEMQL_WORK_ARCHIVE_CONTAINER" DefaultModelCallRetentionDays = 90 DefaultObservationRetentionDays = 180 // DefaultAbandonedAfterSeconds is 60s: TWICE the 30s fleet heartbeat // window, so a run is abandoned only after two missed beats. The // scheduled automation passes this explicitly; the default is here for a // hand call. DefaultAbandonedAfterSeconds = 60 )
const DefaultApprovalTTL = 24 * time.Hour
DefaultApprovalTTL matches the sink this replaces: long enough that a person who approves in the morning can run the same workflow that afternoon, short enough that a forgotten approval does not outlast the awareness of why it was given.
const DefaultPipelinesRunRetentionDays = 30
const DefaultSystemRunRetentionDays = 30
const DefaultWorkerInvocationDeletedRetentionDays = 1
const EnvPipelinesRunRetentionDays = "MEMQL_PIPELINES_RUN_RETENTION_DAYS"
EnvPipelinesRunRetentionDays is how long a finished pipeline run is kept (epic memql#5478, #5496): its v1:pipelines:run row, the v1:work:run it compiled into with that run's steps, and the v1:work:goal behind them once no run of it remains. One window for all three, so an unblocked run's rows leave in the same sweep; a work run something keeps (detail on a longer window, a child that is not its own) stays behind, and its goal with it, until that clears. The Library files a run's steps archived -- logs, artifacts -- are the owner's, and no policy here names them.
const EnvSystemRunRetentionDays = "MEMQL_WORK_SYSTEM_RUN_RETENTION_DAYS"
const EnvWorkerInvocationDeletedRetentionDays = "MEMQL_WORKER_INVOCATION_DELETED_RETENTION_DAYS"
EnvWorkerInvocationDeletedRetentionDays is how long a SOFT-DELETED worker invocation is kept before it is archived and deleted: counted from the tombstone, which workerInvocationRetentionSweep (dsl/worker) writes once a row is older than MEMQL_WORKER_INVOCATION_RETENTION_DAYS. The tombstone IS the retention decision; this is only the grace before the physical delete.
Before 2026-11-08 the tombstone reset the row's age. Physical retention judges a record by its NEWEST version, the tombstone was that version, and the only invocation policy was the 90-day one -- so a row hidden at day 90 was deleted at day 180, and a row that never reached a terminal outcome, which that policy does not select, was never deleted at all. One day after the tombstone, whatever the outcome: a row the sweep hid at 90 days is gone by day 91, and the tombstone version lives a day.
const ProcedureConstructVariable = workstate.ProcedureConstructVariable
ProcedureConstructVariable is the variable compile adds to the run of a goal a learned procedure serves. The one definition is component/work's, which says why a recording must not inherit it.
const ProcedureReplayTriggerPrefix = "procedure:"
ProcedureReplayTriggerPrefix marks a run a learned procedure's REPLAY RUNNER opened: its triggeredBy is `procedure:<mode>` (integrations/procedure, replay.go). Such a run is that runner's and never this dispatcher's (epic memql#5408).
It names an automation -- the construct it replays -- and carries no goal, which is exactly the shape the sweep's backstop offers back on recovery and the admission below takes. Taken, it is run a SECOND time: the template executor cannot load a procedure's bundle as a template, so it FAILS the live replay `automation_not_runnable`, and the terminal status releases the replay's workbench mid-step. So no recovery path offers one, and neither check of the admission takes one. The one judgment the sweep still makes of a replay run is the one it makes of every run: its heartbeat.
integrations/procedure cannot be imported from here -- it imports this package through integrations/planner -- so it spells the prefix itself, and its learn_test.go pins the two spellings together.
const TrainingSubjectAction = "trainSpecialist"
TrainingSubjectAction is the value an approval's subject carries to mean "this decision is about training a specialist". A field rather than a dedicated approval KIND, because a kind is a GATE (which question is being asked of a person) and `skillMint` already asks it; a new kind would need a case in every switch over kinds and buy nothing.
Variables ¶
var ErrRemedyNotWaiting = errors.New("work: the run is no longer waiting on this remedy")
ErrRemedyNotWaiting is a remedy write refused because the run is no longer parked on the wait the remedy was serving: it was cancelled, decided, or moved on while the remedy worked. Its current state stands.
var ErrRunAlreadyClosed = errors.New("work: the run had already finished; its own close stands")
ErrRunAlreadyClosed is FailRun's answer for a run that reached a terminal status before the failure could be written. The run's own close stands, and the caller says so rather than reporting a failure it did not record.
Functions ¶
func AppDispatchSource ¶
func AppDispatchSource(choice common.RouteChoice, owner string) string
AppDispatchSource recognizes only a persisted, owner-selected Apps route. Auto and policy chains may fall back elsewhere and keep normal arbitration.
func CaptureSpine ¶
func CaptureSpine(name string) (*workflowhost.Snapshot, error)
CaptureSpine accepts only an installed template name. Intake uses it before opening any rows. The stored closure then crosses every planner hop without relying on a process cache or substituting the current installation's code.
func GoalCallTags ¶
GoalCallTags is the call tags a goal's origin gives every model call of its runs (spec 2026-10-29, D5): a goal a pipeline opened -- a failed run's diagnosis, the repository change it requests -- records `requestedVia: "pipeline"`, and its calls carry the `pipeline` tag, which the shipped rule pipelineLocalFirst routes to the owner's machines first.
ONE DERIVATION FOR EVERY NODE THAT REBUILDS A RUN CONTEXT FROM ROWS: the agent's work dispatcher and the planner's remedy both read the goal row on the replica doing the work, so the tag never travels in memory from the replica that opened the goal.
func IsDriverOwnedRun ¶
IsDriverOwnedRun reports a run whose DRIVER writes and runs it, so this dispatcher never may: a procedure's replay run (ProcedureReplayTriggerPrefix), a pipeline's run (pipelines.WorkTriggerPrefix, epic memql#5477), and a Go-written journal (workjournal.TriggerPrefix) -- the Library's analysis pass, the D7 delegate's child run, and an app session's recording.
A journal has exactly the shape this dispatcher takes for compiled goal work -- `running`, a goal, and an automationName that is a template WORD naming no automation -- and until it carried the marker, every agent replica claimed each one a millisecond after it opened, could not load the template, and failed it automation_not_runnable over what its driver was recording. Every admission here asks this: the subscriber before the claim, dispatchRun, CanDispatchStoredRun, the sweep's recovery paths, and the privileged re-read (app/work_run_fence.go), which asks it of the STORED row because an id-only event carries no triggeredBy at all.
Types ¶
type ActRefusal ¶
ActRefusal is an act refused for a reason a surface can name.
func (*ActRefusal) Error ¶
func (e *ActRefusal) Error() string
type ApprovalSeed ¶
type ApprovalSeed struct {
ApprovalId string
RunId string
StepKey string
Kind string
Subject map[string]any
ArtifactHash string
Question string
Options []map[string]any
Evidence map[string]any
RequestedAt time.Time
ExpiresAt time.Time
}
ApprovalSeed is the exported shape of one human gate. It mirrors the unexported seed exactly; the conversion in RaiseApproval is what keeps the two from drifting, because a field added to one and not the other will not compile.
type Archiver ¶
type Archiver interface {
Upload(ctx context.Context, container, object string, data []byte, contentType string) (string, error)
}
Archiver is the narrow slice of object storage the retention sweep needs. integrations/azureblob's uploader satisfies it; tests hold a map.
type CompileRequest ¶
type CompileRequest struct {
Spine map[string]any
StartedAt time.Time
ExecutionAuthority map[string]any
GoalId string
RunId string
OwnerUserId string
Statement string
Input map[string]any
Ceilings map[string]any
}
CompileRequest is reconstructed from the authoritative run and goal on the planner. No caller-local run, actor, or budget context is assumed to survive the graph event that crosses the node boundary.
type Compiler ¶
type Compiler interface {
// Compile runs the compile order for one run. It is called on a
// DETACHED goroutine, so it must not assume the caller's context is
// still live and must journal its own failures onto the run.
Compile(ctx context.Context, req CompileRequest)
}
Compiler is what createGoal dispatches to once the goal and its first run exist. It is a SEAM rather than an implementation because compile is the other half of epic A2: the catalog lookup, the three prompts and the Gate-1 sandbox compile-and-bind. The ORDER it must follow is already pure and authored in the installed Spine. This interface binds the native runtime to that frozen workflow, preserving its run authority and budgets.
type DirectGoal ¶
type DirectGoal struct {
ParentRunID string
// AccountIds and Ceilings apply the same scope and limits as a compiled goal.
AccountIds []string
Ceilings map[string]any
// BeforeRun binds a caller-owned record to these identities before the run's
// running event makes it eligible for execution on another replica.
BeforeRun func(context.Context, string, string) error
OwnerUserId string
// Statement is the goal in the requester's words -- the prompt, or what
// the deliverable is. It is what a person sees in Nexus.
Statement string
// AutomationName is the template to run. It must name a @template
// automation; the run dispatcher refuses anything it cannot resolve.
AutomationName string
// Input binds into that template's declared args at fire time.
Input map[string]any
// RequestedVia records the surface it arrived through.
RequestedVia string
// TriggeredBy is recorded on the run.
TriggeredBy string
}
DirectGoal is a goal whose template is already known.
type DispatchRequest ¶
type DispatchRequest struct {
// Recovery is set by the sweep, a freshly rechecked automatic wait, or an
// exact stale-state recovery hint; never by an ordinary graph event.
Recovery bool
// AppPlacement is set only after the execution seam reads the owned journal.
// RecoverySnapshot binds a recovery hint to the exact stale run state.
AppPlacement bool
AppRouteHint bool
RecoverySnapshot string
RunId string
GoalId string
OwnerUserId string
AutomationName string
Variables map[string]any
// Status is what the event said the run was. It is a HINT, not a fact:
// the seam re-reads the row under the journal's actor and refuses if it
// has moved. Carried so the seam can say what it was told when the two
// disagree, which is the difference between "a race" and "a bug".
Status string
// RerunRequestId is the re-run request the event's row carried
// (run.rerun.requestId, epic memql#5414), empty for every other run. The
// claim is keyed on it -- see runClaimKey -- and the seam serves the
// request only under a claim for that request.
RerunRequestId string
// HumanResumeId binds an answered question to its own once-only claim.
HumanResumeId string
// HumanResumeRecovery is set only by the execution seam after a fresh
// stale-heartbeat check. It permits leased takeover of the SAME answer claim if its prior
// claimant died before recording the resumed intent. No second key is used.
HumanResumeRecovery bool
// InferenceWait binds automatic availability recovery to one exact wait.
// The timer is only a hint; CanDispatchStoredRun checks the current row
// after the durable claim, including its approval and due timestamp.
InferenceWait string
// TriggeredBy is the run's triggeredBy, as the event or the sweep's row
// read carried it. Unlike Status it is not a hint: createWorkRun writes it
// once and updateWorkRun does not accept it, so every copy of it is the
// stored value. It is what marks a run another runner owns (runnerOwned):
// a procedure's replay run or a pipeline's run.
TriggeredBy string
// RetryWait is the `since` of the failure path's `retry` wait this dispatch
// serves (memql#5664), set only by that wait's own serving (serveRetry)
// for a run no re-run request can be written for. The claim is keyed on it
// (runClaimKey), so the claim an earlier execution still holds on the bare
// run id does not hold the retry back, and the seam admits the waiting run
// only while it is still parked on that very wait (CanDispatchStoredRun).
RetryWait string
}
DispatchRequest is everything the executor side needs, read off the run row once so the seam does no graph reads of its own.
func (DispatchRequest) CanDispatchStoredRun ¶
func (r DispatchRequest) CanDispatchStoredRun(goalId, status string, waitingOn map[string]any, now time.Time) bool
CanDispatchStoredRun rechecks an event or explicit recovery request against the authoritative row. Ordinary journals belong to their scheduler; only the sweep can take one over. A waiting run is eligible solely for a retry that is DUE and explicitly requested, never a stale event: a due inference wait bound by its exact identity, or a due `retry` wait the failure path parked on (memql#5664), asked for by that wait's own serving (serveRetry) and only while the run is still parked on the very wait it names (RetryWait) -- a dispatch for one failure never serves the next. A replan or repair wait is never eligible here: it is the planner's remedy, not an execution. A driver-owned run is never eligible (IsDriverOwnedRun).
type Dispatcher ¶
type Dispatcher interface {
// Dispatch executes one run's automation. Called on a DETACHED
// goroutine, so it must not assume the caller's context is live, and it
// reports its own outcome onto the run rather than returning it.
Dispatch(ctx context.Context, req DispatchRequest)
}
Dispatcher executes the automation a compiled run names.
A SEAM, for the reason Compiler is one: executing an automation needs the automation Loader, a step registry and an Executor, none of which this package has or should acquire -- they are assembled in app/, which is also where the build tag deciding "is this an agent node" lives.
type Engine ¶
type Engine interface {
Execute(ctx context.Context, query string) (*memqlengine.ExecuteResult, error)
}
Engine is the narrow surface this package needs. *memql.MemQLEngine satisfies it directly.
type Integration ¶
type Integration struct {
// contains filtered or unexported fields
}
Integration exposes the work capabilities.
func (*Integration) ApprovalGuidanceAvailable ¶
ApprovalGuidanceAvailable projects the same eligibility used by the decision path. Opening a discussion neither consumes the request nor resumes work.
func (*Integration) AskAboutFailedRemedy ¶
func (i *Integration) AskAboutFailedRemedy(ctx context.Context, ownerUserId, runId, stepKey, kind, reason string) error
AskAboutFailedRemedy parks a run whose remedy could not be carried out on a person's question, and is what keeps a failing remedy from looping.
Left on its wait, a replan that failed after its model call would be served again by the next pass -- another reasoning-level call, every lease, for ever. So once a remedy has spent its attempt, the run moves off the remedy wait onto a `feedback` approval naming why, the shape the failure path's own questions take (work.FailureApproval, so its approve and its answers can be decided): Retry resumes the run from the step it failed at, Abandon stops it.
func (*Integration) AskComputerScope ¶
func (*Integration) AskFeedback ¶
func (i *Integration) AskFeedback(ctx context.Context, owner, runID, question, kind string, options []map[string]any, expires time.Time) (string, error)
AskFeedback creates and parks under the same cross-replica decision lock used by the answer path. A retry cannot create a second inbox item or park over a decision already made by the person.
func (*Integration) AskFeedbackPresented ¶
func (i *Integration) AskFeedbackPresented(ctx context.Context, owner, runID, question, kind, presentation string, options []map[string]any, expires time.Time, optional bool) (string, error)
AskFeedbackPresented is AskFeedbackWithPolicy with how the question is shown: presentation "" shows it as words, and workstate.FeedbackPresentationLayouts as a choice of built-in email layouts -- kind choice, every option's value a layout id, stored as the exact id it names -- which Ask shows as the layouts' wireframes.
A WIREFRAME IS THE SERVER'S TO DRAW. One a caller put on an option is dropped whatever the presentation, so a model never puts a picture of its own in front of a person; a choice of layouts gets each layout's wireframe drawn here, as every picker draws it (emaildoc.BuiltinWireframe). The drawings ride the stored options alone. The question's subject -- what an answer is checked against and what the question's id is hashed from -- holds the options as asked, so a question with no presentation is stored byte for byte as it always was, and a choice of layouts keeps its id however its layouts come to be drawn.
func (*Integration) AskFeedbackWithPolicy ¶
func (i *Integration) AskFeedbackWithPolicy(ctx context.Context, owner, runID, question, kind string, options []map[string]any, expires time.Time, optional bool) (string, error)
AskFeedbackWithPolicy asks a question shown as words (no presentation).
func (*Integration) AskPlanReview ¶
func (i *Integration) AskPlanReview(ctx context.Context, owner, runID string, subject map[string]any, question string) (string, error)
AskPlanReview parks the current run on an exact, immutable proposal. The DSL chooses the question and placement; shared native machinery owns the receipt.
func (*Integration) CancelComputerUseRuns ¶
func (i *Integration) CancelComputerUseRuns(ctx context.Context, ownerUserId string) (checked, asked int, err error)
CancelComputerUseRuns asks every in-flight run of one owner that has actually dispatched to one of their machines to stop.
It returns how many runs it looked at and how many it asked, because the difference is the whole claim: "checked 9, asked 2" is the selection being narrow, and "checked 9, asked 9" on a cluster doing other work would mean it had stopped being.
func (*Integration) Capabilities ¶
func (i *Integration) Capabilities() []memql.IntegrationCapability
Capabilities implements memql.IntegrationProvider. Each Name is the last segment of the @executor FQN its builtin declares; the registry namespaces them as integration.work.<name>. TestCapabilityNamesMatchTheDSL asserts the set against dsl/work/builtins.memql, because a capability the DSL names and the registry lacks is a BOOT failure on every node type.
func (*Integration) CheckExecutionDestination ¶
func (i *Integration) CheckExecutionDestination(ctx context.Context, runID, target string) error
func (*Integration) Claim ¶
func (i *Integration) Claim(ctx context.Context, id string, req permission.Request, registrationID, machineID string) (*permission.Scope, error)
func (*Integration) ContinueWorkProgress ¶
func (i *Integration) ContinueWorkProgress(ctx context.Context, rc common.RunContext, spent workstate.Spent, estimatedTokens int) (bool, error)
ContinueWorkProgress is reached only after a soft estimate has been spent. It records a bounded extension for newly completed work, never for elapsed time, a heartbeat, an assertion of progress or a repeated failed call.
func (*Integration) DispatchRun ¶
func (i *Integration) DispatchRun(ctx context.Context, runId, ownerUserId string) bool
DispatchRun is the entry the sweep's backstop uses: it knows only a run id, because it found the run by reading rows rather than by being told. The rest of the request is filled in behind the seam's privileged read.
It reports whether it CLAIMED the run, which is the sweep's whole decision: a claimed run has a live replica on it and must not be abandoned this pass.
func (*Integration) EnableCompileViaEvent ¶
func (i *Integration) EnableCompileViaEvent()
EnableCompileViaEvent marks this replica as able to hand compile to the cluster through the run graph event. Called once from mesh / BFF bootstrap on every node that accepts createGoal but does not run compile itself.
First call wins, matching SetCompiler: two halves of one deployment must not disagree about whether a nil compiler is a forward or a refuse.
func (*Integration) FailRun ¶
func (i *Integration) FailRun(ctx context.Context, ownerUserId, runId, code, message string) error
FailRun closes a run the dispatcher could not execute.
It exists because the two failures a dispatcher has -- an automation that will not resolve, and a run refused on its arguments -- both happen BEFORE the executor opens its journal, so nothing else would ever write a terminal status. Left alone, such a run sits at `running` with no heartbeat and the abandoned sweep closes it about a minute later saying the node running it stopped answering. That sentence is true of a node loss and false here, and it sends whoever reads it at the infrastructure.
IT NEVER OVERWRITES A FINISHED RUN. The dispatcher decides from a read made about a second earlier -- loading the template happens in between -- and the run's own driver can close it in that window. The write was unconditional, so a driver's real failure (an app session's, with the machine's reason) was replaced by automation_not_runnable. So the run is re-read immediately before the write and failed only from a status it can still be failed from: running, compiling or waiting -- waiting included, because a waiting inference-retry run whose template cannot load would otherwise stay parked and be redispatched every lease. A read-then-write is the strongest guard updateWorkRun allows (a mutation has no conditional form); it narrows the window from a template load to one round trip.
A run the owner's actor cannot see -- the deployment's own, whose owner is present-and-empty -- is failed as before: there is nothing to judge it by, and refusing would leave it for the abandoned sweep's node-loss sentence.
The write borrows the owner's authority, as every write in this package does; a blank owner is the deployment's own run and stays blank.
func (*Integration) Find ¶
func (i *Integration) Find(ctx context.Context, req permission.Request) (*permission.Grant, error)
Find reads on this replica without consuming. The actual stream holder claims the receipt, so forwarding can never spend a one-time decision twice.
func (*Integration) HandleRunEvent ¶
func (i *Integration) HandleRunEvent(ev events.Event)
HandleRunEvent is the event-bus subscriber for graph.node.{created,updated}.v1:work:run.
It is deliberately cheap and total: almost every run event is one this node should ignore (a step boundary's heartbeat, a terminal close, a run belonging to a status that wants nothing), and the claim -- the only expensive part -- is reached by a small minority.
This subscriber is fed by its own writes, and that is fine ¶
Executing a run writes step rows and updates the run row, each of which broadcasts another v1:work:run event that arrives back here. The claim is what closes the loop: the first event claims and every later one loses. Without it this is an infinite dispatch cycle through the graph, which is the failure `journalSkipsAutomation` exists to prevent on the automation side.
func (*Integration) HasLiveGoalForResponsibility ¶
func (i *Integration) HasLiveGoalForResponsibility(ctx context.Context, ownerUserId, responsibilityId string) (bool, error)
HasLiveGoalForResponsibility reports whether a non-terminal goal already exists for this responsibility -- the C1 dedup guard.
It returns an ERROR rather than a bool on a read failure, and the caller decides. The plan version swallowed the error and answered "no live plan", on the reasoning that the in-process respawn guard covers the duplicate; the error is surfaced here so that reasoning is the CALLER's, stated at the call site, rather than buried in a read.
func (*Integration) HoldWorkRunLifecycle ¶
HoldWorkRunLifecycle is a native journal seam, not a registered capability. Terminal cancellation bookkeeping shares the public Stop/rerun fence. The journal must re-read the exact owned execution under the returned hold.
func (*Integration) InstallReplan ¶
func (i *Integration) InstallReplan(ctx context.Context, ownerUserId, runId string, t ReplanTemplate) error
InstallReplan makes a re-planned template the run's own and hands the run back to the cluster (epic memql#5127, design D12).
THE TEMPLATE FIELDS ARE COMPILE'S, written the way WorkCompiler.Compile writes them -- automationName, templateConstructId, templateFingerprint, templateVersion -- because the executing node loads a run's template from exactly those (app/work_template.go), and checks the fingerprint against the journal before it resumes.
THE RUN STARTS FROM A REQUEST OF ITS OWN (memql#5664). The install writes a `replan` re-run request naming the first step of the new template the run has not finished, with the steps from there on stale, and the agents serve it exactly as they serve a re-run: under a claim keyed on the request, so the claim the failed execution still holds on the bare run id -- four minutes from its own dispatch, never released -- does not strand the run; the completed prefix served from the run's own rows; the new steps run as their first versions. With no request the run was claimed on the bare id, lost to that lease on every agent, and was closed as abandoned a minute later.
THE FAILED STEP THE TEMPLATE DROPPED IS SUPERSEDED FIRST. Its row stays `failed` otherwise, a resume point for a step no template has; written `skipped` before the run moves -- the run's write is what starts it -- the journal says the step is behind the run, and a journal with no request and no failure in its template stays unresumable, as it must be for a second replica claiming from one of the executing replica's events.
func (*Integration) IntegrationName ¶
func (i *Integration) IntegrationName() string
IntegrationName implements memql.IntegrationProvider.
func (*Integration) LimitReplyBudget ¶
func (i *Integration) LimitReplyBudget(ctx context.Context, ownerUserId, runId string) error
LimitReplyBudget is the compiler's narrow write seam. The run's ownership is read under the caller's authority before any server-only mutation.
func (*Integration) LimitWorkloadBudget ¶
func (i *Integration) LimitWorkloadBudget(ctx context.Context, ownerUserId, runId, workload string) error
LimitWorkloadBudget records an estimate separately from the person's hard limits. Discovery may revise that estimate; it can never revise those limits.
func (*Integration) LoadReplanContext ¶
func (i *Integration) LoadReplanContext(ctx context.Context, ownerUserId, runId, stepKey string) (ReplanContext, error)
LoadReplanContext reads the context for one run's replan under the OWNER's borrowed authority, the way every read in this package does. A run whose steps cannot be read yields an error rather than an empty prefix: replanning against a prefix that is empty because the read failed would re-emit every completed step, which is precisely the failure the prefix exists to prevent.
func (*Integration) LockPlanReview ¶
func (i *Integration) LockPlanReview(ctx context.Context, approvalID string) (func(), error)
LockPlanReview serializes replacing a proposal with deciding it. Consumers take this gate before their document gate, matching the shared decision path.
func (*Integration) NewSink ¶
func (i *Integration) NewSink(opts SinkOptions) *Sink
NewSink builds the work-backed approval sink.
func (*Integration) OpenAnalysisGoal ¶
func (i *Integration) OpenAnalysisGoal(ctx context.Context, requestKey string, g DirectGoal) (ReviewGoalReceipt, error)
OpenAnalysisGoal starts a stable, owner-bound request immediately. The DSL template decides where to request review; no approval is manufactured here.
func (*Integration) OpenDirectGoal ¶
func (i *Integration) OpenDirectGoal(ctx context.Context, g DirectGoal) (goalId, runId string, err error)
OpenDirectGoal opens a goal whose template the caller already knows, and starts its run immediately.
Why this exists rather than going through compile ¶
Compile's job is to DECIDE which template a goal needs, cheapest tier first: exact catalog match, near match, then one triage call. Here there is nothing to decide -- `agent()` means "run this agent" and `produceArtifact` means "produce this deliverable", and each already names its template.
Routing them through compile anyway would cost a model call PER INVOCATION, and always the most expensive tier: the catalog matches on a normalized goal STATEMENT, the statement here IS the user's prompt, and no two prompts are alike -- so the exact and near tiers could never hit and every call would reach triage. That is exactly the "no EXTRA model call versus today" line in memql#5048's acceptance, and it is why the Plan path these replace did not decompose either (`startPlanDirect`, memql#816).
The run opens at `running`, not `compiling` ¶
`compiling` means "a template has not been chosen yet", and one has. Opening there and immediately updating would emit two run events and leave a window in which the abandoned sweep sees a run in `compiling` -- which it deliberately does not touch, so a crash in that window strands the run forever.
func (*Integration) OpenPipelineSecurityGoal ¶
func (i *Integration) OpenPipelineSecurityGoal(ctx context.Context, requestKey string, g DirectGoal) (ReviewGoalReceipt, error)
OpenPipelineSecurityGoal is the internal, owner-bound admission seam for one verified finding. The caller binds requestKey to owner/source/scanner/finding, and BeforeRun revalidates its source and live scan consent before each write. A later scan retains the original evidence instead of changing an in-flight proposal. A closed goal stays closed: only its owner may reopen accepted work. Partial bootstrap resumes on another replica under the same durable gate.
func (*Integration) OpenResponsibilityGoal ¶
func (i *Integration) OpenResponsibilityGoal(ctx context.Context, g ResponsibilityGoal) (string, string, error)
OpenResponsibilityGoal opens a goal for a responsibility, opens its first run in `compiling`, and dispatches compile -- the same three writes in the same order as handleCreateGoal, and for the same reason: the run exists before any template is known so the model calls COMPILATION makes have a home from the first one.
The difference from handleCreateGoal is only whose actor writes the goal. There the caller IS the owner and the goal is written under their own actor; here the caller is the reactive loop running as the cluster, so the owner's authority is borrowed for the goal as well as for the run.
func (*Integration) OpenReviewGoal ¶
func (i *Integration) OpenReviewGoal(ctx context.Context, requestKey string, g DirectGoal, subject map[string]any, question string) (ReviewGoalReceipt, error)
OpenReviewGoal opens a known template already waiting for human approval. The calling integration must authorize and capture its immutable proposal before this call, and revalidate source access/revisions before executing. This is an internal Go seam, not a capability accepting arbitrary templates. No run is published as running during bootstrap; the existing Nexus decision flow is the only way to release it. A partially written request is recoverable.
func (*Integration) PauseReplanForBudget ¶
func (i *Integration) PauseReplanForBudget(ctx context.Context, ownerUserId, runId, stepKey string, ceiling *memql.RunCeilingError) error
PauseReplanForBudget preserves the suspended remedy in the approval itself. A decision on another replica must resume planning, not the old failed step. The original cause is separate from the budget breach and all usage survives.
func (*Integration) PauseWorkForBudget ¶
func (i *Integration) PauseWorkForBudget(ctx context.Context, ceiling *memql.RunCeilingError, checkpoint string) (string, error)
PauseWorkForBudget owns one decision for the goal run, even when the active agent turn is several synchronous automation invocations below it.
func (*Integration) PauseWorkForModelCall ¶
func (i *Integration) PauseWorkForModelCall(ctx context.Context, failure, checkpoint, question string) (string, error)
PauseWorkForModelCall preserves the same child and effects. This is not an approval to replay an automation or to increase any model/run allowance.
func (*Integration) PrepareWorkTool ¶
func (i *Integration) PrepareWorkTool(ctx context.Context) (bool, error)
PrepareWorkTool promotes a quick estimate once execution actually needs a capability. This is evidence from execution, not a second classifier call.
func (*Integration) RaiseApproval ¶
func (i *Integration) RaiseApproval(ctx context.Context, ownerUserId string, a ApprovalSeed) (string, error)
RaiseApproval writes one human gate and returns its id. Used by the healing subscriber, whose typed patches must reach a person as a planReview approval rather than being applied (design decision D5: never a silent edit, even to the run's own draft template).
func (*Integration) RecordCompileOutcome ¶
func (i *Integration) RecordCompileOutcome(ctx context.Context, ownerUserId, runId string, fields map[string]any) error
RecordCompileOutcome advances a run with what compile decided: the template it chose, the variables it bound, and the status to move to. Fields not named keep their prior value.
func (*Integration) RecordToolInvocation ¶
func (i *Integration) RecordToolInvocation(ctx context.Context, rec agentintegration.ToolInvocation) error
RecordToolInvocation writes one tool_result observation.
Satisfies agent.ToolInvocationRecorder. The interface is declared on the agent side and implemented here, so the dependency points work -> agent and there is no cycle.
func (*Integration) RecoverableApprovalGuidance ¶
func (i *Integration) RecoverableApprovalGuidance(ctx context.Context, approval map[string]any) string
RecoverableApprovalGuidance lets a reopened discussion offer continuation of an already-recorded answer. It never turns an edited draft into a new grant.
func (*Integration) RequestRepair ¶
func (i *Integration) RequestRepair(ctx context.Context, ownerUserId, runId, stepKey, violation string) error
RequestRepair carries out a contract miss's repair (spec section E): the failed step re-runs with the violation as guidance, the completed prefix is served and never runs again, and the run never restarts from the start.
IT IS A RE-RUN REQUEST, the one rerunStep writes (rerun.go), so the agent serves it on the path a person's re-run takes: the step runs as a new version, and the violation reaches its model calls as "what was wrong with the previous version" -- the override's guidance, read at the model seam. A deterministic step has no model call to read it, so for one the repair is a re-run, which is all such a step can act on. Nobody asked for it, so it names no requester and no author.
func (*Integration) RestoreInferenceWaits ¶
func (i *Integration) RestoreInferenceWaits(ctx context.Context) (int, error)
RestoreInferenceWaits reconstructs this agent's lost timers after startup. Event subscriptions start at the current stream watermark; an already parked wait emits no event when an agent returns. During rolling upgrades the cron leader may also run an older sweep, so startup must not depend on its nudge. This bounded maintenance read spans owners, but each timer restores exactly its run owner's authority and rechecks the fresh row before claiming work. It neither writes a heartbeat nor admits an effect on the maintenance actor.
func (*Integration) RetentionSweep ¶
func (i *Integration) RetentionSweep(ctx context.Context, dryRun bool) (RetentionResult, error)
RetentionSweep folds, archives, then deletes -- in that order, and no further than the order allows.
# The fold comes FIRST, and that is the one ordering that destroys evidence if reversed
A run's summary is folded onto the run row BEFORE its detail goes, so a run stays readable after (design section D, "Retention"). Deleting first would leave a run that never got its summary and whose detail is gone -- there is no recovery from that inside the cluster.
NO ARCHIVE MEANS NO DELETE ¶
The log store's rule, reused. A cluster with no archive container keeps its journal and this says so, every night, in Refused. There is deliberately no TimescaleDB retention policy on these rows for exactly this reason: a policy cannot be told to wait for an upload.
func (*Integration) RunBudget ¶
func (i *Integration) RunBudget(ctx context.Context, ownerUserId, runId string) (work.Ceilings, error)
RunBudget reports the ceilings a run inherits from its goal.
WHY THE CEILINGS AND NOT THE SPEND. Run closure and budget pauses persist accounting snapshots, including PauseReplanForBudget, but a live run's row can lag answered calls and reserved provider attempts. A missing field is unknown usage, never zero. Callers must reconcile the native usage receipts at admission rather than treating this allowance projection as spend or as permission to infer. The run's durable renewals apply on every serving role.
Read under the OWNER's borrowed authority, like every other read here: the goal is owner-tiered, and an unstamped read answers zero rows and no error, which would present as "this goal has no ceilings" -- unbounded.
func (*Integration) ServeAnswerChecks ¶
func (i *Integration) ServeAnswerChecks(c RunClaimer)
ServeAnswerChecks designates this node as one that serves the answer validator's check, claimed through c among the nodes so designated. Which nodes those are is app/'s decision (app/integrations_work_validator.go), made once at boot.
func (*Integration) SetAppRecoveryPublisher ¶
func (i *Integration) SetAppRecoveryPublisher(publish func(events.Event))
func (*Integration) SetArchiver ¶
func (i *Integration) SetArchiver(a Archiver)
SetArchiver installs object storage for the retention sweep.
func (*Integration) SetCompiler ¶
func (i *Integration) SetCompiler(c Compiler)
SetCompiler installs the compile surface. Called once, from the node that runs compile, before the first goal. A later call is ignored for the reason packages' SetWorkbench states: two halves of one run must not disagree about where the work went.
func (*Integration) SetDispatcher ¶
func (i *Integration) SetDispatcher(d Dispatcher)
SetDispatcher installs the execution surface. Called once, from the node that runs steps. First call wins, as SetCompiler does.
func (*Integration) SetGateDB ¶
func (i *Integration) SetGateDB(gate func() *sql.DB)
SetGateDB installs the resolver of the pool this integration's write gates run on (memql#6022): the gate pool, not the request pool.
func (*Integration) SetNow ¶
func (i *Integration) SetNow(f func() time.Time)
SetNow injects a clock. Tests only.
func (*Integration) SetPlanReviewAnswerValidator ¶
func (i *Integration) SetPlanReviewAnswerValidator(kind string, validate func(context.Context, map[string]any, map[string]any) error)
SetPlanReviewAnswerValidator binds a typed selection to an immutable proposal. The owning integration validates its contract; Work persists and replays the person's exact answer under the existing cross-replica decision lock.
func (*Integration) SetPlanReviewValidator ¶
func (i *Integration) SetPlanReviewValidator(kind string, validate func(context.Context, map[string]any) error)
SetPlanReviewValidator installs the integration that can check the current source behind a captured proposal. Each accepting replica needs this wiring.
func (*Integration) SetRemedy ¶
func (i *Integration) SetRemedy(r Remedy)
SetRemedy installs the remedy seam. A nil remedy is a working state: replan and repair waits stay parked and are logged once per pass rather than silently dropped.
func (*Integration) SetRunClaimer ¶
func (i *Integration) SetRunClaimer(c RunClaimer)
SetRunClaimer installs the cross-replica claim.
A nil claimer does NOT mean "claim nothing". Dispatch refuses without one: see dispatchRun. That is the opposite of the usual nil-is-degraded rule in this package, and deliberately so -- every other nil seam here costs a feature, while this one costs exactly-once on side effects.
func (*Integration) StepVersions ¶
StepVersions is every version of every step of one run, one entry per (step row, version), each the NEWEST row-version of that version -- the receipt when there is one, the intent while it runs, the re-assertion after a head move. A row written before versions were a field takes its attempt as its version, and the entry carries it as `version`. Sorted by seq, then row id, then version. Nested steps are included; the head decisions keep to the top-level ones.
The actor in ctx decides which rows are admitted, exactly as a query's would: the caller's own for the version-history builtin, the owner's borrowed authority for a Go caller acting on the owner's behalf. Exported for the dispatcher and the other Go callers that need a run's full history.
func (*Integration) SweepWaiting ¶
func (i *Integration) SweepWaiting(ctx context.Context, olderThan time.Duration) (WaitSweepResult, error)
SweepWaiting resumes due timers and closes runs whose node stopped answering.
type ModelJournal ¶
type ModelJournal struct {
// contains filtered or unexported fields
}
ModelJournal implements memqlengine.ModelCallJournal over v1:work:modelCall.
func NewModelJournal ¶
func NewModelJournal(engine Engine) *ModelJournal
NewModelJournal builds the journal over an engine. Returns nil for a nil engine, so app/ can wire unconditionally and a binary with no engine gets a live-only seam rather than a panic.
func (*ModelJournal) Decide ¶
func (j *ModelJournal) Decide(ctx context.Context, rc common.RunContext, requestHash string) memqlengine.ModelCallVerdict
Decide answers what to do with one model request, and is the ONE caller of work.DecideServe.
THE DECISION LIVES HERE, beside the rows it is made from. component/work is the pure half and this package is, in its own header's words, "only responsible for OBEYING those decisions" -- so the engine asks and this answers. It also keeps component/work out of component/memql's go.mod, and therefore out of the fifteen modules that import the engine.
A READ FAILURE IS NOT A MISS. A miss is an ordinary answer that DecideServe is built to receive and, under the strict policy, turns into a divergence blaming the prompt. A database that could not be reached is a different thing and says so, so the run stops with the real reason rather than with a confident wrong one.
func (*ModelJournal) Record ¶
func (j *ModelJournal) Record(ctx context.Context, ownerUserId string, c memqlengine.JournaledCall) error
Record writes one v1:work:modelCall row.
type OperationalRetentionResult ¶
type OperationalRetentionResult struct {
Concept string `json:"concept"`
Env string `json:"env"`
RetentionDays int `json:"retentionDays"`
Candidates int `json:"candidates"`
ArchivedVersions int `json:"archivedVersions"`
DeletedVersions int `json:"deletedVersions"`
Objects []string `json:"objects,omitempty"`
Oversized []string `json:"oversized,omitempty"`
// BudgetExhausted says this policy ran out of its share of retentionRunBudget
// (retentionShare) with versions stored in day windows it had not read, so
// candidates may remain. The next pass resumes its persisted checkpoint. A policy that read every window up to its cutoff, or
// had nothing stored before it, leaves it unset however much of its share it
// used.
BudgetExhausted bool `json:"budgetExhausted,omitempty"`
}
type Remedy ¶
type Remedy interface {
// Replan re-plans from the failed step on, KEEPING the completed prefix.
// Never from the start: the steps that already succeeded are evidence
// rather than a draft, and re-planning over them is the unguided rerun
// the debugging literature measured as substantially worse than localized
// repair. Returns whether it took the run.
Replan(ctx context.Context, runId, ownerUserId, stepKey, reason string) bool
// Repair re-runs ONE failed step with the violation as guidance, leaving
// every other step alone. Returns whether it took the run.
Repair(ctx context.Context, runId, ownerUserId, stepKey, violation string) bool
}
Remedy is the seam the two acts that need more than a row go through. Implemented by integrations/planner, wired from app/ on the planner node.
type ReplanContext ¶
type ReplanContext struct {
Statement string
CompletedSteps []map[string]any
FailedStep map[string]any
// The sealed source is evidence for the repair, including real argument
// names, agent ids and private dependencies on another replica.
TemplateName string
Template []memql.SandboxConstruct
// Recorded is every top-level step the run holds a row for, by key, with
// its status. It is what a re-planned template is checked against before
// it is installed: resume serves a step from its row only BEFORE the
// resume point, so a completed step the new template puts after the first
// step the run never reached would run a second time.
Recorded map[string]string
// Variables are what the run's resume binds into its template's args
// before any step runs: the run's stored variables, or its triggering
// event's payload when it has none -- component/automations' ResumeFrom
// rule. A re-planned template is held to them before it is installed
// (memql#5664).
Variables map[string]any
}
ReplanContext is what the replanGap prompt needs and only this package can read: the goal in the person's own words, the steps that already succeeded, and the step the plan broke at.
THE COMPLETED PREFIX IS THE POINT. The steps that already ran are EVIDENCE, not a draft: re-planning from the start is the unguided rerun the debugging literature measured as substantially worse than localized repair, and it also re-executes side effects that already happened. The prompt is shown them as fixed and instructed never to re-emit them.
type ReplanTemplate ¶
type ReplanTemplate struct {
AutomationName string
TemplateConstructId string
TemplateFingerprint string
TemplateVersion string
// StepKeys are the new template's top-level step keys, in order.
StepKeys []string
// ResumeAt is the first of them the run has not given a finished version:
// where the install's request starts the run.
ResumeAt string
// Outcome is what the re-plan did, for the run's outcome.
Outcome map[string]any
}
ReplanTemplate is a re-planned template that passed Gate 1 and was persisted the way compile persists a draft: what InstallReplan records on the run.
type ResponsibilityGoal ¶
type ResponsibilityGoal struct {
// OwnerUserId is the responsibility's owner, and becomes the goal's.
OwnerUserId string
// ResponsibilityId is v1:planner:responsibility.id, recorded on the goal
// so the dedup guard below can find it again.
ResponsibilityId string
// Statement is the directive in the person's own words.
Statement string
// Input is the typed input the compile pass binds.
Input map[string]any
}
ResponsibilityGoal is a goal the reactive loop wants opened.
type RetentionResult ¶
type RetentionResult struct {
JournalCandidates int `json:"journalCandidates"`
Operational []OperationalRetentionResult `json:"operational,omitempty"`
BoundaryModelCall string `json:"boundaryModelCall"`
BoundaryObservation string `json:"boundaryObservation"`
RunsSummarized int `json:"runsSummarized"`
RowsArchived int `json:"rowsArchived"`
RowsDeleted int `json:"rowsDeleted"`
Objects []string `json:"objects,omitempty"`
Container string `json:"container,omitempty"`
DryRun bool `json:"dryRun,omitempty"`
// Oversized names every record kept because it alone is more than one
// archive object holds (retireSplitting), journal and operational alike.
Oversized []string `json:"oversized,omitempty"`
// Refused says why nothing was deleted, when nothing was. It is a
// SENTENCE rather than a flag because the operator response differs: no
// container is a configuration choice, a failed upload is an incident.
Refused string `json:"refused,omitempty"`
Took string `json:"took"`
}
RetentionResult is what one retention pass did.
type ReviewGoalReceipt ¶
type ReviewGoalReceipt struct {
GoalID string `json:"goalId"`
RunID string `json:"runId"`
ApprovalID string `json:"approvalId"`
}
ReviewGoalReceipt identifies one request, including after an interrupted bootstrap or a lost response. None of these identities change on retry.
func ReviewGoalIdentity ¶
func ReviewGoalIdentity(owner, requestKey string) ReviewGoalReceipt
ReviewGoalIdentity lets the requesting integration recover its own receipt. It confers no authority; every read still uses the caller's owner-scoped query.
type RunCeilings ¶
type RunCeilings struct {
// contains filtered or unexported fields
}
RunCeilings implements memqlengine.RunCeilingGuard over v1:work:goal's ceilings and v1:work:modelCall's rows.
func NewRunCeilings ¶
func NewRunCeilings(engine Engine, logger *slog.Logger) *RunCeilings
NewRunCeilings builds the guard over an engine. Returns nil for a nil engine, so app/ can wire unconditionally.
func (*RunCeilings) Admit ¶
func (c *RunCeilings) Admit(ctx context.Context, rc common.RunContext, estimatedTokens int) *memqlengine.RunCeilingBreach
Admit reports the ceiling this run has reached, or nil.
A run with no goal on its context is admitted without a read: ceilings live on the goal, so there is nothing declared to check.
func (*RunCeilings) AdmitProvider ¶
func (c *RunCeilings) AdmitProvider(ctx context.Context, rc common.RunContext, policy memql.ProviderAdmission) error
The provider boundary counts actual inference attempts, including auxiliary embeddings and transport retries, separately from logical answered requests. One immutable cumulative receipt per admission avoids a lifetime-sized ID set. The write gate spans fresh accounting, progress checks and the reservation; a lost response conservatively consumes an attempt, never grants a refund.
func (*RunCeilings) Charge ¶
func (c *RunCeilings) Charge(ctx context.Context, rc common.RunContext, spend memqlengine.ModelSpend)
Charge records one answered request against the run.
IT CHARGES EVEN WHEN THE RUN IS UNBOUNDED, because "unbounded" is a fact about this goal's ceilings and the figures are still what a reader sees on the park of a SIBLING run -- and because a ceiling raised mid-run would otherwise start counting from zero.
func (*RunCeilings) Deadline ¶
func (c *RunCeilings) Deadline(ctx context.Context, rc common.RunContext) (time.Time, error)
Deadline lets an admitted operation finish within the original hard limit. Soft workload windows are checked between calls, where progress can be saved and assessed. Neither a retry nor a replica hop restarts the clock.
func (*RunCeilings) DeclaredDeadline ¶
func (c *RunCeilings) DeclaredDeadline(ctx context.Context, rc common.RunContext) (time.Time, error)
DeclaredDeadline verifies the goal/run binding but imposes no lifetime deadline. A context deadline cannot be renewed by progress after it is made, and used to kill productive tool loops at two hours. Admission checks renewable windows; individual model/tool requests retain their own timeout and idle watchdogs. Cancellation and permission expiry remain independent controls.
func (*RunCeilings) ModelCallBudget ¶
func (c *RunCeilings) ModelCallBudget(ctx context.Context, rc common.RunContext) (limit, used int, err error)
ModelCallBudget observes the current progress window and reconciled receipt union without admitting, charging or renewing a call. Recovery must use the same cumulative allowance as admission: the original goal estimate becomes stale after a durable renewal and would force archival forever once spent. Provider hard caps remain independently enforced at dispatch.
func (*RunCeilings) Spent ¶
func (c *RunCeilings) Spent(_ context.Context, rc common.RunContext) memqlengine.RunSpend
Spent reports the run's spend so far, for a refusal to carry onto the row.
type RunClaimer ¶
type RunClaimer interface {
ClaimWithTTL(ctx context.Context, name, dedupKey string, ttl time.Duration) bool
}
RunClaimer is the cross-replica gate. Satisfied by *automations.ClusterExecutionGuard, which is what app/ installs; declared as a local interface so this package does not import the automations package for one method.
type SessionWriter ¶
type SessionWriter struct {
// contains filtered or unexported fields
}
SessionWriter records an app session's actions.
It satisfies workerservice.SessionRecorder. The MCP node's recorder uses the same type through the same methods, which is what keeps one account of what an app did rather than two that can disagree.
func NewSessionWriter ¶
func NewSessionWriter(engine Engine, logger *slog.Logger) *SessionWriter
NewSessionWriter builds the writer over the engine.
func (*SessionWriter) CloseRecording ¶
func (w *SessionWriter) CloseRecording(ctx context.Context, r workerservice.RecordingClose) error
CloseRecording writes the app_answer step and closes the run.
The structured answer is a STEP rather than only the run's outcome because it is the one part of the session that IS intelligence (component/work reads `app_answer` as reasoning), and a lift that could not see it would treat the whole session as deterministic.
func (*SessionWriter) HeartbeatRecording ¶
func (w *SessionWriter) HeartbeatRecording(ctx context.Context, r workerservice.RecordingHeartbeat) error
HeartbeatRecording says the recording run is still being written.
The run is this writer's, not the dispatcher's, so no executor beats for it -- and the work sweep abandons a running run whose heartbeat is a minute old, which is every session longer than a minute. The replica holding the session calls this from its flush, throttled.
It names the heartbeat and nothing else: updateWorkRun is a read-merge, and any other field named here would be rewritten on every beat.
func (*SessionWriter) OpenRecording ¶
func (w *SessionWriter) OpenRecording(ctx context.Context, r workerservice.RecordingOpen) (string, error)
OpenRecording returns the run the session's actions are recorded into.
A run the CALLER already opened is kept as-is and nothing is written. That is the ordinary path since epic memql#5391: the delegate opens the subrun and stamps `childRunId` on the delegating step, and opening a second one here would leave that pointer aimed at a run holding one step and no actions -- the "points at nothing" failure the delegate's own comment warns about.
With no run, one is opened here and the delegating step is stamped, which is the delegated-task path: nothing handed a step over, so nothing opened a run for it.
A MODEL CALL (r.ModelCall) is opened here too, and claims less: it names the calling run as its parent -- which is what makes the session traceable to the work that caused it -- and nothing else. See RecordingOpen.ModelCall.
func (*SessionWriter) RecordAction ¶
func (w *SessionWriter) RecordAction(ctx context.Context, r workerservice.RecordedAction) error
RecordAction writes one action as a step and an observation.
TWO ROWS, NOT ONE, and the split is the spine's: the STEP is what happened and is what a later lift reads to build a procedure; the OBSERVATION is the evidence, carrying the arguments whole, the result digest and the Library ids of whatever the action read or wrote. A step alone could not be replayed; an observation alone would not be in the run's order.
func (*SessionWriter) RecordGap ¶
func (w *SessionWriter) RecordGap(ctx context.Context, r workerservice.RecordedGap) error
RecordGap notes actions that never arrived.
IT IS AN OBSERVATION RATHER THAN A FIELD, and the reason is that the loss has to be IN THE RUN'S OWN RECORD. A counter on the session row says a session lost something; an observation says WHERE, in the same stream a later lift is already reading, so a procedure built from an incomplete recording is built by something that had to walk past the hole.
func (*SessionWriter) SetNow ¶
func (w *SessionWriter) SetNow(now func() time.Time)
SetNow makes the clock injectable, so a rendered timestamp is an assertable value in a test.
type Sink ¶
type Sink struct {
// contains filtered or unexported fields
}
Sink is the safety.ApprovalSink that writes v1:work:approval rows.
It REPLACES component/safety/approval's v1:safety:approvalRequest sink (design section D: the approval concept "replaces the plan's feedbackRequest and feedbackResponse, the canvas cards and the safety gate's ask sink"). Wire it in app/safety_llm.go's buildSafetyApprovalSink.
The contract this must not break ¶
safety.ApprovalSink says: errors are recovered, logged internally, and returned as Unconfigured -- a dead approval sink must not crash live traffic. Every failure path below therefore answers Unconfigured, which leaves the Gate's pre-approval Ask refusal exactly as it was.
Why the correlation key IS the artifact hash ¶
safety.ApprovalCorrelationKey is a stable digest of the descriptor's identifying surface over the REDACTED payload, and it is already the key the gate uses to collapse retries of the same action onto one row. Reusing it as artifactHash means a MODIFIED command hashes differently, finds no approved row, and raises a fresh approval -- which is the artifact-hash guarantee, obtained by construction. Computing a second, different hash here would give the row two identities and make "is this the thing I approved" answerable two ways.
func (*Sink) Check ¶
func (s *Sink) Check(ctx context.Context, desc safety.ActionDescriptor, cls safety.Classification) safety.ApprovalVerdict
Check implements safety.ApprovalSink.
type SinkOptions ¶
type SinkOptions struct {
Logger *slog.Logger
// TTL is how long an approved row acts as a bypass. Zero takes
// DefaultApprovalTTL.
TTL time.Duration
}
SinkOptions configure NewSink.
type WaitSweepResult ¶
type WaitSweepResult struct {
Checked int `json:"checked"`
Resumed int `json:"resumed"`
Abandoned int `json:"abandoned"`
// Redispatched counts runs that looked abandoned and were handed back to
// a live replica instead of being closed. See redispatchStale.
Redispatched int `json:"redispatched"`
OrphanedWaitsClosed int `json:"orphanedWaitsClosed"`
}
WaitSweepResult is what one pass found.
Source Files
¶
- acts.go
- app_dispatch.go
- approval.go
- approval_discussion.go
- approval_guidance.go
- branch.go
- budget_checkpoint.go
- compile.go
- compile_surface.go
- computer_permission_recovery.go
- computer_permissions.go
- continue.go
- continue_receipt.go
- continue_window.go
- dispatch.go
- evaluation_scope.go
- execution_destination.go
- failure_waits.go
- feedback.go
- fork.go
- goal.go
- goal_acceptance.go
- goal_call_tags.go
- goal_evaluation.go
- head.go
- human_feedback.go
- inference_waits.go
- integration.go
- killswitch.go
- knowledge_consultation.go
- model_catalog_research.go
- model_checkpoint.go
- modeljournal.go
- observation.go
- operational_retention.go
- optional_feedback.go
- outcome_recovery.go
- owner_identity.go
- pipeline_security_goal.go
- progress_capability_receipts.go
- progress_continuation.go
- progress_credits.go
- progress_receipt_paging.go
- progress_recheck.go
- progress_recovery.go
- provider_admission.go
- provider_phase.go
- recovery_heads.go
- remedy_budget.go
- replan_template.go
- rerun.go
- retention_progress.go
- retitle.go
- review_goal.go
- routing_review.go
- run_authority.go
- run_lifecycle.go
- run_recovery_budget.go
- runceilings.go
- session.go
- skill_selection.go
- snapshot.go
- spine.go
- store.go
- sweep.go
- training.go
- validator.go
- versions.go
- workload_ceilings.go