Interface: SpendDayStore
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:39
The rows a day's bound needs, kept by the caller; every method runs inside the caller's transaction. A store that
holds fenced reservations says so with fencedReservations and implements addFencedReservation and
deferReservation, persisting the fence, the next check and the evidence in the caller's transaction. A store
without that capability cannot admit a fenced reservation or run a sweep with a resolver. A store that holds
operation reservations says so with operationReservations and implements addOperationReservation,
openOperationReservation, beginRun, endRun and renewRun; a store without them cannot admit an operation.
Properties
fencedReservations?
readonlyoptionalfencedReservations:true
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:60
True on a store that holds fenced reservations, with addFencedReservation and deferReservation.
operationReservations?
readonlyoptionaloperationReservations:true
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:66
True on a store that holds operation reservations, with the five methods below.
Methods
addFencedReservation()?
optionaladdFencedReservation(reservation):Promise<string>
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:62
Records a reservation as addReservation does, made with requireFence, and answers its id.
Parameters
reservation
created
Date
day
string
expires
Date
kind
string
micro
number
Returns
Promise<string>
addOperationReservation()?
optionaladdOperationReservation(row):Promise<string|null>
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:72
Records an operation's row in the locked day with run 1's own row, its recorded figure run 1's bound and run 1
holding the lease, adds micro to the day's open total, and answers its id; null, changing nothing, when the
operation has a row already.
Parameters
row
created
Date
day
string
expires
Date
kind
string
leaseUntil
Date
micro
number
operation
string
runMicro
number
Returns
Promise<string | null>
addReservation()
addReservation(
reservation):Promise<string>
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:46
Records a reservation in the locked day, adds it to the day's open total, and answers its id.
Parameters
reservation
created
Date
day
string
expires
Date
kind
string
micro
number
Returns
Promise<string>
beginRun()?
optionalbeginRun(id,run):Promise<RunBegin>
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:80
In one locked step: gone when the row is settled or past its expiry at at; in_flight while a lease is live;
gone when it has had maxRuns runs or runMicro would take its recorded figure past its amount; else the run's
bound added to the recorded figure, the run counted, its own row written and the lease given to it.
Parameters
id
string
run
at
Date
leaseUntil
Date
maxRuns
number
runMicro
number
Returns
Promise<RunBegin>
deferReservation()?
optionaldeferReservation(id,retryAt,evidence):Promise<boolean>
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:64
Atomically persists a permanent fence, next check and evidence; false for a closed or unknown row.
Parameters
id
string
retryAt
Date
evidence
SpendFenceEvidence | undefined
Returns
Promise<boolean>
endRun()?
optionalendRun(id,end):Promise<RunEnd>
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:87
In one transaction, all or nothing: the run's own row takes settledMicro held to its bound, unless it ended
already, when nothing changes; then, only when run holds the lease of an open row, its bound in the recorded
figure is replaced by that figure, the lease cleared, and the row settled at its recorded figure when at is past
its expiry or close is set.
Parameters
id
string
end
at
Date
close
boolean
run
number
settledMicro
number
Returns
Promise<RunEnd>
expiredReservations()
expiredReservations(
at):Promise<OpenReservation[]>
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:58
The open reservations whose time is up at at. A store with fencedReservations leaves a deferred one out until
its next check has come, and lists each one's requireFence and last evidence. A store with
operationReservations lists an operation's row only once it is past its expiry with no live lease, its micro
the recorded figure, which releaseExpiredSpend settles it at.
Parameters
at
Date
Returns
Promise<OpenReservation[]>
lockDay()
lockDay(
day):Promise<number>
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:44
Makes the day's row when it is missing, locks it for the transaction, and answers its committed total in whole micro-dollars; any other answer refuses the admission.
Parameters
day
string
Returns
Promise<number>
openOperationReservation()?
optionalopenOperationReservation(operation):Promise<OperationReservation|null>
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:74
The operation's row, or null.
Parameters
operation
string
Returns
Promise<OperationReservation | null>
renewRun()?
optionalrenewRun(id,renew):Promise<boolean>
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:93
In one locked step: true, the lease moved to leaseUntil, only when run holds a lease still live at at on an
open row; false, changing nothing, otherwise. A run renews its lease before it settles what it holds outside the
row (a unit on another meter), so no other run can begin and take that unit over while it settles it.
Parameters
id
string
renew
at
Date
leaseUntil
Date
run
number
Returns
Promise<boolean>
settleReservation()
settleReservation(
id,settledMicro,at):Promise<boolean>
Defined in: packages/agentos/src/safety/runtime/SpendReservations.ts:51
Settles an open reservation once, at settledMicro held to the amount reserved: the day's open total loses the
amount and its settled total gains what settled. Answers false, changing nothing, for one already settled or unknown.
Parameters
id
string
settledMicro
number
at
Date
Returns
Promise<boolean>