work

package
v0.0.0-...-86254be Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 48 Imported by: 0

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

View Source
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.

View Source
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
)
View Source
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.

View Source
const DefaultPipelinesRunRetentionDays = 30
View Source
const DefaultSystemRunRetentionDays = 30
View Source
const DefaultWorkerInvocationDeletedRetentionDays = 1
View Source
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.

View Source
const EnvSystemRunRetentionDays = "MEMQL_WORK_SYSTEM_RUN_RETENTION_DAYS"
View Source
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.

View Source
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.

View Source
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.

View Source
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

View Source
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.

View Source
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

func GoalCallTags(goal map[string]any) []string

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

func IsDriverOwnedRun(triggeredBy string) bool

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

type ActRefusal struct {
	Code    string
	Message string
}

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 New

func New(engine Engine, logger *slog.Logger, database ...func() *bun.DB) *Integration

New constructs the integration. Tests call this with a stub engine.

func (*Integration) ApprovalGuidanceAvailable

func (i *Integration) ApprovalGuidanceAvailable(ctx context.Context, approval map[string]any) bool

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 (i *Integration) AskComputerScope(ctx context.Context, owner, runID string, subject map[string]any) (string, error)

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

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

func (i *Integration) HoldWorkRunLifecycle(ctx context.Context) (*memql.GateHold, error)

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

func (i *Integration) StepVersions(ctx context.Context, runId string) ([]map[string]any, error)

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

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

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

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

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

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

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址