Skip to content

Stores

TidStore

Bases: Protocol

Structural Protocol for tRFC/qRFC TID duplicate-execution guards (D-01).

Implementers provide a durable backend (database, Redis, …). Clients that implement all five methods satisfy this Protocol without any inheritance (structural / duck-typing — D-01 / PEP 544).

Security contract (T-06-S01)

tid values are peer-influenced 24-character strings from the RFC TID alphabet (ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789/_=@-). Treat tid as untrusted input: use parameterised queries; never concatenate tid into SQL strings or file paths. Length is expected to be 24 chars (RFC_TID_LN in SDK type definitions) but the store MUST NOT silently normalise or truncate — document any length enforcement as part of the backend contract.

Source code in src/saprfclib/stores.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
@runtime_checkable
class TidStore(Protocol):
    """Structural Protocol for tRFC/qRFC TID duplicate-execution guards (D-01).

    Implementers provide a durable backend (database, Redis, …). Clients
    that implement all five methods satisfy this Protocol without any inheritance
    (structural / duck-typing — D-01 / PEP 544).

    Security contract (T-06-S01)
    -----------------------------
    ``tid`` values are peer-influenced 24-character strings from the RFC TID
    alphabet (``ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789/_=@-``). Treat ``tid`` as
    **untrusted input**: use parameterised queries; never concatenate ``tid``
    into SQL strings or file paths. Length is expected to be 24 chars
    (``RFC_TID_LN`` in SDK type definitions) but the store MUST NOT silently normalise
    or truncate — document any length enforcement as part of the backend contract.
    """

    def is_executed(self, tid: str) -> bool:
        """Return True if ``tid`` has already been executed (committed)."""
        ...

    def mark_received(self, tid: str) -> None:
        """Record that ``tid`` has been received and is now in-flight."""
        ...

    def mark_executed(self, tid: str) -> None:
        """Record that the function module for ``tid`` executed successfully."""
        ...

    def mark_rolled_back(self, tid: str) -> None:
        """Record that the execution for ``tid`` was rolled back (error path)."""
        ...

    def confirm(self, tid: str) -> None:
        """Confirm ``tid``; may remove or archive it from active tracking."""
        ...

    def park(self, tid: str, payload: bytes) -> None:
        """Store serialised request bytes alongside TID state for later re-drive (D-03b).

        ``bytes(payload)`` copies are stored — caller mutations to the source
        buffer do not affect the stored payload.

        Security contract (T-06-S01): ``tid`` is peer-influenced untrusted input.
        Use parameterised queries; never concatenate ``tid`` into SQL or file paths.
        """
        ...

    def get_parked(self, tid: str) -> bytes | None:
        """Return the parked payload for ``tid``, or ``None`` if not parked (D-03b).

        Security contract (T-06-S01): ``tid`` is peer-influenced untrusted input.
        Use parameterised queries; never concatenate ``tid`` into SQL or file paths.
        """
        ...

    def list_parked(self) -> list[str]:
        """Return a list of TIDs that currently have a non-null parked payload (D-03b)."""
        ...

    def delete_parked(self, tid: str) -> None:
        """Remove the parked payload for ``tid``; get_parked then returns None (D-03b).

        Security contract (T-06-S01): ``tid`` is peer-influenced untrusted input.
        Use parameterised queries; never concatenate ``tid`` into SQL or file paths.
        """
        ...

is_executed 

is_executed(tid)

Return True if tid has already been executed (committed).

Source code in src/saprfclib/stores.py 
139
140
141
def is_executed(self, tid: str) -> bool:
    """Return True if ``tid`` has already been executed (committed)."""
    ...

mark_received 

mark_received(tid)

Record that tid has been received and is now in-flight.

Source code in src/saprfclib/stores.py 
143
144
145
def mark_received(self, tid: str) -> None:
    """Record that ``tid`` has been received and is now in-flight."""
    ...

mark_executed 

mark_executed(tid)

Record that the function module for tid executed successfully.

Source code in src/saprfclib/stores.py 
147
148
149
def mark_executed(self, tid: str) -> None:
    """Record that the function module for ``tid`` executed successfully."""
    ...

mark_rolled_back 

mark_rolled_back(tid)

Record that the execution for tid was rolled back (error path).

Source code in src/saprfclib/stores.py 
151
152
153
def mark_rolled_back(self, tid: str) -> None:
    """Record that the execution for ``tid`` was rolled back (error path)."""
    ...

confirm 

confirm(tid)

Confirm tid; may remove or archive it from active tracking.

Source code in src/saprfclib/stores.py 
155
156
157
def confirm(self, tid: str) -> None:
    """Confirm ``tid``; may remove or archive it from active tracking."""
    ...

park 

park(tid, payload)

Store serialised request bytes alongside TID state for later re-drive (D-03b).

bytes(payload) copies are stored — caller mutations to the source buffer do not affect the stored payload.

Security contract (T-06-S01): tid is peer-influenced untrusted input. Use parameterised queries; never concatenate tid into SQL or file paths.

Source code in src/saprfclib/stores.py 
159
160
161
162
163
164
165
166
167
168
def park(self, tid: str, payload: bytes) -> None:
    """Store serialised request bytes alongside TID state for later re-drive (D-03b).

    ``bytes(payload)`` copies are stored — caller mutations to the source
    buffer do not affect the stored payload.

    Security contract (T-06-S01): ``tid`` is peer-influenced untrusted input.
    Use parameterised queries; never concatenate ``tid`` into SQL or file paths.
    """
    ...

get_parked 

get_parked(tid)

Return the parked payload for tid, or None if not parked (D-03b).

Security contract (T-06-S01): tid is peer-influenced untrusted input. Use parameterised queries; never concatenate tid into SQL or file paths.

Source code in src/saprfclib/stores.py 
170
171
172
173
174
175
176
def get_parked(self, tid: str) -> bytes | None:
    """Return the parked payload for ``tid``, or ``None`` if not parked (D-03b).

    Security contract (T-06-S01): ``tid`` is peer-influenced untrusted input.
    Use parameterised queries; never concatenate ``tid`` into SQL or file paths.
    """
    ...

list_parked 

list_parked()

Return a list of TIDs that currently have a non-null parked payload (D-03b).

Source code in src/saprfclib/stores.py 
178
179
180
def list_parked(self) -> list[str]:
    """Return a list of TIDs that currently have a non-null parked payload (D-03b)."""
    ...

delete_parked 

delete_parked(tid)

Remove the parked payload for tid; get_parked then returns None (D-03b).

Security contract (T-06-S01): tid is peer-influenced untrusted input. Use parameterised queries; never concatenate tid into SQL or file paths.

Source code in src/saprfclib/stores.py 
182
183
184
185
186
187
188
def delete_parked(self, tid: str) -> None:
    """Remove the parked payload for ``tid``; get_parked then returns None (D-03b).

    Security contract (T-06-S01): ``tid`` is peer-influenced untrusted input.
    Use parameterised queries; never concatenate ``tid`` into SQL or file paths.
    """
    ...

UnitStore

Bases: Protocol

Structural Protocol for bgRFC Unit lifecycle tracking (D-02).

Keyed on (unit_id, unit_type) where unit_type is 'T' (no queues) or 'Q' (queues — Pitfall 5 from RESEARCH.md). Implementers must handle both unit types; the type is part of the key because the same unit_id MUST be tracked separately per type in the bgRFC protocol.

Security contract (T-06-S01)

unit_id values are peer-influenced 32-character uppercase hex strings (RFC_UNITID_LN in SDK type definitions). Treat as untrusted input: use parameterised queries; never concatenate into SQL or file paths. unit_type is 'T' or 'Q'; validate before use.

Source code in src/saprfclib/stores.py 
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
@runtime_checkable
class UnitStore(Protocol):
    """Structural Protocol for bgRFC Unit lifecycle tracking (D-02).

    Keyed on ``(unit_id, unit_type)`` where ``unit_type`` is ``'T'`` (no queues)
    or ``'Q'`` (queues — Pitfall 5 from RESEARCH.md). Implementers must handle
    both unit types; the type is part of the key because the same ``unit_id``
    MUST be tracked separately per type in the bgRFC protocol.

    Security contract (T-06-S01)
    -----------------------------
    ``unit_id`` values are peer-influenced 32-character uppercase hex strings
    (``RFC_UNITID_LN`` in SDK type definitions). Treat as **untrusted input**: use
    parameterised queries; never concatenate into SQL or file paths.
    ``unit_type`` is ``'T'`` or ``'Q'``; validate before use.
    """

    def get_unit_state(self, unit_id: str, unit_type: str) -> UnitState:
        """Return the current :class:`UnitState` for ``(unit_id, unit_type)``.

        Returns ``UnitState.NOT_FOUND`` for unknown units.
        """
        ...

    def persist(self, unit_id: str, unit_type: str) -> None:
        """Persist the Unit; transition state to at least ``IN_PROCESS``."""
        ...

    def confirm(self, unit_id: str, unit_type: str) -> None:
        """Confirm the Unit; transition state to ``CONFIRMED`` or remove entry."""
        ...

    def park(self, unit_id: str, unit_type: str, payload: bytes) -> None:
        """Store serialised request bytes for ``(unit_id, unit_type)`` (D-03b).

        ``bytes(payload)`` copies are stored — caller mutations do not affect
        the stored payload.

        Security contract (T-06-S01): ``unit_id`` / ``unit_type`` are
        peer-influenced untrusted inputs.  Use parameterised queries; never
        concatenate into SQL or file paths.
        """
        ...

    def get_parked(self, unit_id: str, unit_type: str) -> bytes | None:
        """Return the parked payload for ``(unit_id, unit_type)``, or None (D-03b).

        Security contract (T-06-S01): ``unit_id`` / ``unit_type`` are
        peer-influenced untrusted inputs.
        """
        ...

    def list_parked(self) -> list[tuple[str, str]]:
        """Return ``(unit_id, unit_type)`` pairs that have a non-null payload (D-03b)."""
        ...

    def delete_parked(self, unit_id: str, unit_type: str) -> None:
        """Remove the parked payload for ``(unit_id, unit_type)`` (D-03b).

        Security contract (T-06-S01): ``unit_id`` / ``unit_type`` are
        peer-influenced untrusted inputs.
        """
        ...

get_unit_state 

get_unit_state(unit_id, unit_type)

Return the current :class:UnitState for (unit_id, unit_type).

Returns UnitState.NOT_FOUND for unknown units.

Source code in src/saprfclib/stores.py 
213
214
215
216
217
218
def get_unit_state(self, unit_id: str, unit_type: str) -> UnitState:
    """Return the current :class:`UnitState` for ``(unit_id, unit_type)``.

    Returns ``UnitState.NOT_FOUND`` for unknown units.
    """
    ...

persist 

persist(unit_id, unit_type)

Persist the Unit; transition state to at least IN_PROCESS.

Source code in src/saprfclib/stores.py 
220
221
222
def persist(self, unit_id: str, unit_type: str) -> None:
    """Persist the Unit; transition state to at least ``IN_PROCESS``."""
    ...

confirm 

confirm(unit_id, unit_type)

Confirm the Unit; transition state to CONFIRMED or remove entry.

Source code in src/saprfclib/stores.py 
224
225
226
def confirm(self, unit_id: str, unit_type: str) -> None:
    """Confirm the Unit; transition state to ``CONFIRMED`` or remove entry."""
    ...

park 

park(unit_id, unit_type, payload)

Store serialised request bytes for (unit_id, unit_type) (D-03b).

bytes(payload) copies are stored — caller mutations do not affect the stored payload.

Security contract (T-06-S01): unit_id / unit_type are peer-influenced untrusted inputs. Use parameterised queries; never concatenate into SQL or file paths.

Source code in src/saprfclib/stores.py 
228
229
230
231
232
233
234
235
236
237
238
def park(self, unit_id: str, unit_type: str, payload: bytes) -> None:
    """Store serialised request bytes for ``(unit_id, unit_type)`` (D-03b).

    ``bytes(payload)`` copies are stored — caller mutations do not affect
    the stored payload.

    Security contract (T-06-S01): ``unit_id`` / ``unit_type`` are
    peer-influenced untrusted inputs.  Use parameterised queries; never
    concatenate into SQL or file paths.
    """
    ...

get_parked 

get_parked(unit_id, unit_type)

Return the parked payload for (unit_id, unit_type), or None (D-03b).

Security contract (T-06-S01): unit_id / unit_type are peer-influenced untrusted inputs.

Source code in src/saprfclib/stores.py 
240
241
242
243
244
245
246
def get_parked(self, unit_id: str, unit_type: str) -> bytes | None:
    """Return the parked payload for ``(unit_id, unit_type)``, or None (D-03b).

    Security contract (T-06-S01): ``unit_id`` / ``unit_type`` are
    peer-influenced untrusted inputs.
    """
    ...

list_parked 

list_parked()

Return (unit_id, unit_type) pairs that have a non-null payload (D-03b).

Source code in src/saprfclib/stores.py 
248
249
250
def list_parked(self) -> list[tuple[str, str]]:
    """Return ``(unit_id, unit_type)`` pairs that have a non-null payload (D-03b)."""
    ...

delete_parked 

delete_parked(unit_id, unit_type)

Remove the parked payload for (unit_id, unit_type) (D-03b).

Security contract (T-06-S01): unit_id / unit_type are peer-influenced untrusted inputs.

Source code in src/saprfclib/stores.py 
252
253
254
255
256
257
258
def delete_parked(self, unit_id: str, unit_type: str) -> None:
    """Remove the parked payload for ``(unit_id, unit_type)`` (D-03b).

    Security contract (T-06-S01): ``unit_id`` / ``unit_type`` are
    peer-influenced untrusted inputs.
    """
    ...

UnitState

Bases: Enum

Processing state of a bgRFC Unit on the receiver side (RFC_UNIT_STATE).

Maps the five values from RFC_UNIT_STATE in SDK type definitions-332. The string values mirror the ServerSessionState style used elsewhere in this package (consistent string-valued enum.Enum pattern).

Values

NOT_FOUND (0) No information for this unit in the target system. The send may have not reached the target; re-send is appropriate unless CONFIRMED was already seen. IN_PROCESS (1) Backend is persisting (type 'Q') or executing (type 'T') the payload. Wait and poll again. COMMITTED (2) Data persisted (or executed) on the receiver. Confirm event may be sent. ROLLED_BACK (3) An error occurred; unit must be re-sent. CONFIRMED (4) Temporary state after Confirm and before status erasure. No action needed; delete payload and status information on the sender side.

Source code in src/saprfclib/stores.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
class UnitState(enum.Enum):
    """Processing state of a bgRFC Unit on the receiver side (RFC_UNIT_STATE).

    Maps the five values from ``RFC_UNIT_STATE`` in SDK type definitions-332. The
    string values mirror the ``ServerSessionState`` style used elsewhere in
    this package (consistent string-valued enum.Enum pattern).

    Values
    ------
    NOT_FOUND  (0)
        No information for this unit in the target system. The send may have
        not reached the target; re-send is appropriate unless ``CONFIRMED``
        was already seen.
    IN_PROCESS (1)
        Backend is persisting (type 'Q') or executing (type 'T') the payload.
        Wait and poll again.
    COMMITTED  (2)
        Data persisted (or executed) on the receiver. Confirm event may be sent.
    ROLLED_BACK (3)
        An error occurred; unit must be re-sent.
    CONFIRMED  (4)
        Temporary state after Confirm and before status erasure. No action needed;
        delete payload and status information on the sender side.
    """

    NOT_FOUND = "NOT_FOUND"
    IN_PROCESS = "IN_PROCESS"
    COMMITTED = "COMMITTED"
    ROLLED_BACK = "ROLLED_BACK"
    CONFIRMED = "CONFIRMED"

InMemoryTidStore

Thread-safe in-process TID store backed by a dict + threading.Lock.

Process-lifetime only — NOT durable (D-03). Data is lost on process restart. Production deployments must supply a custom durable store (e.g. PostgreSQL, Redis) that satisfies the :class:TidStore Protocol.

Security (T-06-S01): TID keys are stored as-is in a Python dict. This is safe for dict keys; it is the responsibility of durable backend implementers to treat TID values as untrusted (parameterised queries, no concatenation).

Concurrency (T-06-S03): a single threading.Lock guards all mutations.

Source code in src/saprfclib/stores.py 
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
class InMemoryTidStore:
    """Thread-safe in-process TID store backed by a ``dict`` + ``threading.Lock``.

    Process-lifetime only — NOT durable (D-03). Data is lost on process restart.
    Production deployments must supply a custom durable store (e.g. PostgreSQL,
    Redis) that satisfies the :class:`TidStore` Protocol.

    Security (T-06-S01): TID keys are stored as-is in a Python dict. This is
    safe for dict keys; it is the responsibility of durable backend implementers
    to treat TID values as untrusted (parameterised queries, no concatenation).

    Concurrency (T-06-S03): a single ``threading.Lock`` guards all mutations.
    """

    def __init__(self) -> None:
        self._lock: threading.Lock = threading.Lock()
        # Maps tid -> one of _TID_RECEIVED, _TID_EXECUTED, _TID_ROLLED_BACK.
        self._store: dict[str, str] = {}
        # Maps tid -> parked payload bytes (D-03b park contract).
        self._parked: dict[str, bytes] = {}

    def is_executed(self, tid: str) -> bool:
        """Return True if ``tid`` has been marked as executed."""
        with self._lock:
            return self._store.get(tid) == _TID_EXECUTED

    def mark_received(self, tid: str) -> None:
        """Record that ``tid`` arrived; does NOT imply successful execution."""
        with self._lock:
            self._store[tid] = _TID_RECEIVED

    def mark_executed(self, tid: str) -> None:
        """Record successful execution of the function module for ``tid``."""
        with self._lock:
            self._store[tid] = _TID_EXECUTED

    def mark_rolled_back(self, tid: str) -> None:
        """Record rollback (error) for ``tid``; is_executed remains False."""
        with self._lock:
            self._store[tid] = _TID_ROLLED_BACK

    def confirm(self, tid: str) -> None:
        """Confirm ``tid`` and remove it from active tracking (cleanup)."""
        with self._lock:
            self._store.pop(tid, None)

    def park(self, tid: str, payload: bytes) -> None:
        """Store a copy of ``payload`` for later re-drive (D-03b).

        Does not alter TID state — is_executed() is unaffected.

        Security (T-06-S01): ``tid`` is peer-influenced untrusted input; used
        only as a Python dict key here (safe for in-process stores).
        """
        with self._lock:
            self._parked[tid] = bytes(payload)

    def get_parked(self, tid: str) -> bytes | None:
        """Return parked payload for ``tid``, or None if not parked (D-03b).

        Security (T-06-S01): ``tid`` used as Python dict key only (safe).
        """
        with self._lock:
            return self._parked.get(tid)

    def list_parked(self) -> list[str]:
        """Return a list of TIDs that currently have a parked payload (D-03b)."""
        with self._lock:
            return list(self._parked.keys())

    def delete_parked(self, tid: str) -> None:
        """Remove the parked payload for ``tid`` (D-03b).

        Security (T-06-S01): ``tid`` used as Python dict key only (safe).
        """
        with self._lock:
            self._parked.pop(tid, None)

is_executed 

is_executed(tid)

Return True if tid has been marked as executed.

Source code in src/saprfclib/stores.py 
292
293
294
295
def is_executed(self, tid: str) -> bool:
    """Return True if ``tid`` has been marked as executed."""
    with self._lock:
        return self._store.get(tid) == _TID_EXECUTED

mark_received 

mark_received(tid)

Record that tid arrived; does NOT imply successful execution.

Source code in src/saprfclib/stores.py 
297
298
299
300
def mark_received(self, tid: str) -> None:
    """Record that ``tid`` arrived; does NOT imply successful execution."""
    with self._lock:
        self._store[tid] = _TID_RECEIVED

mark_executed 

mark_executed(tid)

Record successful execution of the function module for tid.

Source code in src/saprfclib/stores.py 
302
303
304
305
def mark_executed(self, tid: str) -> None:
    """Record successful execution of the function module for ``tid``."""
    with self._lock:
        self._store[tid] = _TID_EXECUTED

mark_rolled_back 

mark_rolled_back(tid)

Record rollback (error) for tid; is_executed remains False.

Source code in src/saprfclib/stores.py 
307
308
309
310
def mark_rolled_back(self, tid: str) -> None:
    """Record rollback (error) for ``tid``; is_executed remains False."""
    with self._lock:
        self._store[tid] = _TID_ROLLED_BACK

confirm 

confirm(tid)

Confirm tid and remove it from active tracking (cleanup).

Source code in src/saprfclib/stores.py 
312
313
314
315
def confirm(self, tid: str) -> None:
    """Confirm ``tid`` and remove it from active tracking (cleanup)."""
    with self._lock:
        self._store.pop(tid, None)

park 

park(tid, payload)

Store a copy of payload for later re-drive (D-03b).

Does not alter TID state — is_executed() is unaffected.

Security (T-06-S01): tid is peer-influenced untrusted input; used only as a Python dict key here (safe for in-process stores).

Source code in src/saprfclib/stores.py 
317
318
319
320
321
322
323
324
325
326
def park(self, tid: str, payload: bytes) -> None:
    """Store a copy of ``payload`` for later re-drive (D-03b).

    Does not alter TID state — is_executed() is unaffected.

    Security (T-06-S01): ``tid`` is peer-influenced untrusted input; used
    only as a Python dict key here (safe for in-process stores).
    """
    with self._lock:
        self._parked[tid] = bytes(payload)

get_parked 

get_parked(tid)

Return parked payload for tid, or None if not parked (D-03b).

Security (T-06-S01): tid used as Python dict key only (safe).

Source code in src/saprfclib/stores.py 
328
329
330
331
332
333
334
def get_parked(self, tid: str) -> bytes | None:
    """Return parked payload for ``tid``, or None if not parked (D-03b).

    Security (T-06-S01): ``tid`` used as Python dict key only (safe).
    """
    with self._lock:
        return self._parked.get(tid)

list_parked 

list_parked()

Return a list of TIDs that currently have a parked payload (D-03b).

Source code in src/saprfclib/stores.py 
336
337
338
339
def list_parked(self) -> list[str]:
    """Return a list of TIDs that currently have a parked payload (D-03b)."""
    with self._lock:
        return list(self._parked.keys())

delete_parked 

delete_parked(tid)

Remove the parked payload for tid (D-03b).

Security (T-06-S01): tid used as Python dict key only (safe).

Source code in src/saprfclib/stores.py 
341
342
343
344
345
346
347
def delete_parked(self, tid: str) -> None:
    """Remove the parked payload for ``tid`` (D-03b).

    Security (T-06-S01): ``tid`` used as Python dict key only (safe).
    """
    with self._lock:
        self._parked.pop(tid, None)

InMemoryUnitStore

Thread-safe in-process bgRFC Unit store backed by a dict + threading.Lock.

Process-lifetime only — NOT durable (D-03). Data is lost on process restart. Production deployments must supply a custom durable store that satisfies the :class:UnitStore Protocol.

Unit state key is (unit_id, unit_type) so that the same unit_id may coexist with different types (Pitfall 5 — 'T' and 'Q' are distinct).

Security (T-06-S01): keys stored as-is in a Python dict; safe for in-process use. Durable backend implementers must parameterise all queries.

Concurrency (T-06-S03): a single threading.Lock guards all mutations.

Source code in src/saprfclib/stores.py 
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
class InMemoryUnitStore:
    """Thread-safe in-process bgRFC Unit store backed by a ``dict`` + ``threading.Lock``.

    Process-lifetime only — NOT durable (D-03). Data is lost on process restart.
    Production deployments must supply a custom durable store that satisfies the
    :class:`UnitStore` Protocol.

    Unit state key is ``(unit_id, unit_type)`` so that the same ``unit_id``
    may coexist with different types (Pitfall 5 — 'T' and 'Q' are distinct).

    Security (T-06-S01): keys stored as-is in a Python dict; safe for in-process
    use. Durable backend implementers must parameterise all queries.

    Concurrency (T-06-S03): a single ``threading.Lock`` guards all mutations.
    """

    def __init__(self) -> None:
        self._lock: threading.Lock = threading.Lock()
        # Maps (unit_id, unit_type) -> UnitState
        self._store: dict[tuple[str, str], UnitState] = {}
        # Maps (unit_id, unit_type) -> parked payload bytes (D-03b park contract).
        self._parked: dict[tuple[str, str], bytes] = {}

    def get_unit_state(self, unit_id: str, unit_type: str) -> UnitState:
        """Return the :class:`UnitState` for ``(unit_id, unit_type)``.

        Returns :attr:`UnitState.NOT_FOUND` for unknown units.
        """
        with self._lock:
            return self._store.get((unit_id, unit_type), UnitState.NOT_FOUND)

    def persist(self, unit_id: str, unit_type: str) -> None:
        """Persist Unit; set state to :attr:`UnitState.IN_PROCESS`."""
        with self._lock:
            self._store[(unit_id, unit_type)] = UnitState.IN_PROCESS

    def confirm(self, unit_id: str, unit_type: str) -> None:
        """Confirm Unit; set state to :attr:`UnitState.CONFIRMED`."""
        with self._lock:
            self._store[(unit_id, unit_type)] = UnitState.CONFIRMED

    def park(self, unit_id: str, unit_type: str, payload: bytes) -> None:
        """Store a copy of ``payload`` for ``(unit_id, unit_type)`` (D-03b).

        Does not alter unit state — get_unit_state() is unaffected.

        Security (T-06-S01): keys used as Python tuple dict keys only (safe).
        """
        with self._lock:
            self._parked[(unit_id, unit_type)] = bytes(payload)

    def get_parked(self, unit_id: str, unit_type: str) -> bytes | None:
        """Return parked payload for ``(unit_id, unit_type)``, or None (D-03b)."""
        with self._lock:
            return self._parked.get((unit_id, unit_type))

    def list_parked(self) -> list[tuple[str, str]]:
        """Return all ``(unit_id, unit_type)`` pairs with a parked payload (D-03b)."""
        with self._lock:
            return list(self._parked.keys())

    def delete_parked(self, unit_id: str, unit_type: str) -> None:
        """Remove the parked payload for ``(unit_id, unit_type)`` (D-03b).

        Security (T-06-S01): keys used as Python tuple dict keys only (safe).
        """
        with self._lock:
            self._parked.pop((unit_id, unit_type), None)

get_unit_state 

get_unit_state(unit_id, unit_type)

Return the :class:UnitState for (unit_id, unit_type).

Returns :attr:UnitState.NOT_FOUND for unknown units.

Source code in src/saprfclib/stores.py 
378
379
380
381
382
383
384
def get_unit_state(self, unit_id: str, unit_type: str) -> UnitState:
    """Return the :class:`UnitState` for ``(unit_id, unit_type)``.

    Returns :attr:`UnitState.NOT_FOUND` for unknown units.
    """
    with self._lock:
        return self._store.get((unit_id, unit_type), UnitState.NOT_FOUND)

persist 

persist(unit_id, unit_type)

Persist Unit; set state to :attr:UnitState.IN_PROCESS.

Source code in src/saprfclib/stores.py 
386
387
388
389
def persist(self, unit_id: str, unit_type: str) -> None:
    """Persist Unit; set state to :attr:`UnitState.IN_PROCESS`."""
    with self._lock:
        self._store[(unit_id, unit_type)] = UnitState.IN_PROCESS

confirm 

confirm(unit_id, unit_type)

Confirm Unit; set state to :attr:UnitState.CONFIRMED.

Source code in src/saprfclib/stores.py 
391
392
393
394
def confirm(self, unit_id: str, unit_type: str) -> None:
    """Confirm Unit; set state to :attr:`UnitState.CONFIRMED`."""
    with self._lock:
        self._store[(unit_id, unit_type)] = UnitState.CONFIRMED

park 

park(unit_id, unit_type, payload)

Store a copy of payload for (unit_id, unit_type) (D-03b).

Does not alter unit state — get_unit_state() is unaffected.

Security (T-06-S01): keys used as Python tuple dict keys only (safe).

Source code in src/saprfclib/stores.py 
396
397
398
399
400
401
402
403
404
def park(self, unit_id: str, unit_type: str, payload: bytes) -> None:
    """Store a copy of ``payload`` for ``(unit_id, unit_type)`` (D-03b).

    Does not alter unit state — get_unit_state() is unaffected.

    Security (T-06-S01): keys used as Python tuple dict keys only (safe).
    """
    with self._lock:
        self._parked[(unit_id, unit_type)] = bytes(payload)

get_parked 

get_parked(unit_id, unit_type)

Return parked payload for (unit_id, unit_type), or None (D-03b).

Source code in src/saprfclib/stores.py 
406
407
408
409
def get_parked(self, unit_id: str, unit_type: str) -> bytes | None:
    """Return parked payload for ``(unit_id, unit_type)``, or None (D-03b)."""
    with self._lock:
        return self._parked.get((unit_id, unit_type))

list_parked 

list_parked()

Return all (unit_id, unit_type) pairs with a parked payload (D-03b).

Source code in src/saprfclib/stores.py 
411
412
413
414
def list_parked(self) -> list[tuple[str, str]]:
    """Return all ``(unit_id, unit_type)`` pairs with a parked payload (D-03b)."""
    with self._lock:
        return list(self._parked.keys())

delete_parked 

delete_parked(unit_id, unit_type)

Remove the parked payload for (unit_id, unit_type) (D-03b).

Security (T-06-S01): keys used as Python tuple dict keys only (safe).

Source code in src/saprfclib/stores.py 
416
417
418
419
420
421
422
def delete_parked(self, unit_id: str, unit_type: str) -> None:
    """Remove the parked payload for ``(unit_id, unit_type)`` (D-03b).

    Security (T-06-S01): keys used as Python tuple dict keys only (safe).
    """
    with self._lock:
        self._parked.pop((unit_id, unit_type), None)