Skip to content

Frappucc1no/recall-loom / skills/recallloom

recallloom

Flagged

Use when a task involves continuing a project, restoring project context, maintaining file-based project memory, updating current-state summaries, or recording meaningful progress across sessions. Works best for long-horizon, file-based projects and supports research writing, product document collaboration, software project coordination, and broader cross-functional project continuity.

FileKindSize
LICENSEother10.0 KB
NOTICEother190 B
SKILL.mdskill md24.5 KB
managed-assets.jsonconfig1.1 KB
native_commands/README.mdmarkdown1.2 KB
native_commands/claude-code/rl-init.md.tmplother323 B
native_commands/claude-code/rl-resume.md.tmplother290 B
native_commands/claude-code/rl-status.md.tmplother299 B
native_commands/claude-code/rl-validate.md.tmplother277 B
native_commands/gemini-cli/rl-init.toml.tmplother295 B
native_commands/gemini-cli/rl-resume.toml.tmplother262 B
native_commands/gemini-cli/rl-status.toml.tmplother271 B
native_commands/gemini-cli/rl-validate.toml.tmplother249 B
native_commands/opencode/rl-init.md.tmplother286 B
native_commands/opencode/rl-resume.md.tmplother253 B
native_commands/opencode/rl-status.md.tmplother262 B
native_commands/opencode/rl-validate.md.tmplother240 B
package-metadata.jsonconfig1.0 KB
profiles/general-project-continuity.mdmarkdown2.4 KB
profiles/product-doc-collaboration.mdmarkdown2.2 KB
profiles/research-writing.mdmarkdown2.1 KB
profiles/software-project-coordination.mdmarkdown2.8 KB
references/anti-patterns.mdmarkdown2.5 KB
references/contract-registry.jsonconfig7.7 KB
references/contract-schema.jsonconfig7.7 KB
references/file-contracts.mdmarkdown23.4 KB
references/operation-playbooks.mdmarkdown26.5 KB
references/package-support-policy.mdmarkdown9.4 KB
references/profiles.mdmarkdown2.0 KB
references/protocol.mdmarkdown20.5 KB
references/recording-workflow.mdmarkdown9.9 KB
scripts/_common.pyscript87.8 KB
scripts/append_daily_log_entry.pyscript40.4 KB
scripts/archive_logs.pyscript17.6 KB
scripts/commit_context_file.pyscript31.6 KB
scripts/core/__init__.pyscript39 B
scripts/core/bridge/__init__.pyscript30 B
scripts/core/bridge/blocks.pyscript6.9 KB
scripts/core/coldstart/__init__.pyscript26 B
scripts/core/coldstart/sources.pyscript22.4 KB
scripts/core/coldstart/structured.pyscript5.4 KB
scripts/core/continuity/__init__.pyscript34 B
scripts/core/continuity/daily_log.pyscript16.1 KB
scripts/core/continuity/freshness.pyscript15.3 KB
scripts/core/continuity/preflight.pyscript41.0 KB
scripts/core/continuity/quick_summary.pyscript10.9 KB
scripts/core/continuity/workday.pyscript12.3 KB
scripts/core/errors.pyscript838 B
scripts/core/failure/__init__.pyscript47 B
scripts/core/failure/context.pyscript5.6 KB
scripts/core/failure/contracts.pyscript108.6 KB
scripts/core/output/__init__.pyscript35 B
scripts/core/output/confirmation_material.pyscript15.0 KB
scripts/core/output/privacy.pyscript10.5 KB
scripts/core/output/user_status.pyscript5.8 KB
scripts/core/protocol/__init__.pyscript60 B
scripts/core/protocol/contracts.pyscript8.3 KB
scripts/core/protocol/markers.pyscript4.9 KB
scripts/core/protocol/sections.pyscript3.4 KB
scripts/core/protocol/templates.pyscript6.5 KB
scripts/core/provenance/__init__.pyscript67 B
scripts/core/provenance/bindings.pyscript13.2 KB
scripts/core/provenance/evidence.pyscript58.2 KB
scripts/core/provenance/inconsistent_review.pyscript85.6 KB
scripts/core/provenance/receipts.pyscript20.2 KB
scripts/core/provenance/state.pyscript38.0 KB
scripts/core/provenance/store.pyscript43.8 KB
scripts/core/recording/__init__.pyscript1.6 KB
scripts/core/recording/contracts.pyscript31.7 KB
scripts/core/recording/daily_log_append.pyscript30.2 KB
scripts/core/recording/managed_write.pyscript52.8 KB
scripts/core/recording/planner.pyscript20.6 KB
scripts/core/recording/privacy.pyscript1.7 KB
scripts/core/recording/suggestions.pyscript8.6 KB
scripts/core/recording/transaction.pyscript93.3 KB
scripts/core/registry/__init__.pyscript58 B
scripts/core/registry/loader.pyscript18.8 KB
scripts/core/safety/__init__.pyscript30 B
scripts/core/safety/attached_text.pyscript6.9 KB
scripts/core/safety/input_transport.pyscript61.0 KB
scripts/core/safety/prepared_input.pyscript24.4 KB
scripts/core/safety/scratch_residue.pyscript18.8 KB
scripts/core/support/__init__.pyscript53 B
scripts/core/support/cache.pyscript19.4 KB
scripts/core/support/policy.pyscript8.8 KB
scripts/core/trust/__init__.pyscript42 B
scripts/core/trust/state.pyscript4.1 KB
scripts/core/workspace/__init__.pyscript33 B
scripts/core/workspace/atomic_io.pyscript12.2 KB
scripts/core/workspace/runtime.pyscript54.7 KB
scripts/detect_project_root.pyscript3.4 KB
scripts/generate_coldstart_proposal.pyscript7.5 KB
scripts/init_context.pyscript37.8 KB
scripts/install_native_commands.pyscript31.5 KB
scripts/manage_entry_bridge.pyscript20.8 KB
scripts/preflight_context_check.pyscript10.1 KB
scripts/prepare_recovery_promotion.pyscript22.1 KB
scripts/query_continuity.pyscript84.1 KB
scripts/recallloom.pyscript233.7 KB
scripts/recommend_workday.pyscript17.6 KB
scripts/record_recovery_review.pyscript50.9 KB
scripts/remove_context.pyscript13.9 KB
scripts/repair_daily_log_cursor.pyscript33.7 KB
scripts/stage_recovery_proposal.pyscript17.5 KB
scripts/summarize_continuity_status.pyscript43.7 KB
scripts/sync_contract_docs.pyscript11.3 KB
scripts/unlock_write_lock.pyscript8.1 KB
scripts/validate_context.pyscript54.9 KB

scripts/core/workspace/atomic_io.py

View on GitHub
#!/usr/bin/env python3
"""Single owner for atomic file replacement in the RecallLoom write path.

Frozen contract (v0.5.0 unique construction plan §7.7; retry numbers from the
Gate P freeze record §4 item 3):

``atomic_replace_if_unchanged(path, expected_identity, new_bytes, retry_policy)``
has exactly four outcomes:

- ``REPLACED_VERIFIED``: the target now holds exactly ``new_bytes``, proven by
  an exact byte readback after the replace. A target that already holds exactly
  ``new_bytes`` counts as already successful: the mutation is never replayed.
- ``OLD_VERIFIED_RETRYABLE``: every replace attempt failed with an allowlisted
  transient error while the old bytes+identity were still verified exact
  before each attempt, and the bounded retry budget (attempts/deadline) ran
  out. The operation may be retried as a whole; the target was never observed
  in any other state.
- ``EXTERNAL_CHANGE``: the target bytes differ from ``expected_identity``
  (checked before every attempt, including after a backoff). The foreign
  bytes are preserved; the replace is never attempted against a changed
  target.
- ``UNKNOWN``: the target was unreadable, the replace failed with a
  non-allowlisted error, or the post-replace readback failed or mismatched.
  An unknown-result mutation is never replayed.

``expected_identity`` is the exact expected current byte content of the
target; identity equality is byte-exact equality, re-verified before every
attempt. Only allowlisted transient errors may be retried, and only within
the bounded attempts/deadline/backoff budget. Temp-file residue is cleaned on
every outcome.

Retry policy (Gate P freeze record §4 item 3): the Linux transient errno
candidates EAGAIN/EBUSY/ETXTBSY may be retried; EACCES is NOT retried by
default; attempts <= 4, deadline 2 s, backoff 0.05/0.1/0.2 s. The Windows
winerror allowlist is residual W2: the policy is configurable and fails
closed by default (an empty allowlist means no retries at all).

Stdlib only. Core modules must not import scripts/* or ``_common.py``; this
module only depends on ``core.errors`` for the LockBusyError parity wrappers.
"""

from __future__ import annotations

from contextlib import suppress
from dataclasses import dataclass
import errno
import os
from pathlib import Path
import tempfile
import time

from core.errors import LockBusyError

OUTCOME_REPLACED_VERIFIED = "REPLACED_VERIFIED"
OUTCOME_OLD_VERIFIED_RETRYABLE = "OLD_VERIFIED_RETRYABLE"
OUTCOME_EXTERNAL_CHANGE = "EXTERNAL_CHANGE"
OUTCOME_UNKNOWN = "UNKNOWN"
ATOMIC_REPLACE_OUTCOMES = (
    OUTCOME_REPLACED_VERIFIED,
    OUTCOME_OLD_VERIFIED_RETRYABLE,
    OUTCOME_EXTERNAL_CHANGE,
    OUTCOME_UNKNOWN,
)

REASON_ALREADY_NEW_NO_REPLAY = "already_new_no_replay"
REASON_RETRY_BUDGET_EXHAUSTED = "retry_budget_exhausted"
REASON_TARGET_UNREADABLE = "target_unreadable"
REASON_REPLACE_FAILED_NON_TRANSIENT = "replace_failed_non_transient"
REASON_READBACK_FAILED = "readback_failed"
REASON_READBACK_MISMATCH = "readback_mismatch"

# Frozen retry bounds (Gate P freeze record §4 item 3).
MAX_RETRY_ATTEMPTS = 4
MAX_RETRY_DEADLINE_S = 2.0
DEFAULT_BACKOFF_S = (0.05, 0.1, 0.2)

# Linux transient errno candidates proven by P050-E2. ETXTBSY does not exist
# on every platform, so resolve the names defensively.
LINUX_TRANSIENT_ERRNOS = frozenset(
    value
    for value in (
        getattr(errno, "EAGAIN", None),
        getattr(errno, "EBUSY", None),
        getattr(errno, "ETXTBSY", None),
    )
    if value is not None
)


@dataclass(frozen=True)
class AtomicReplaceRetryPolicy:
    """Configurable bounded retry policy; empty allowlists mean no retries."""

    transient_errnos: frozenset[int]
    transient_winerrors: frozenset[int]
    max_attempts: int
    deadline_s: float
    backoff_s: tuple[float, ...]

    def __post_init__(self) -> None:
        if not 1 <= self.max_attempts <= MAX_RETRY_ATTEMPTS:
            raise ValueError(
                f"max_attempts must be within 1..{MAX_RETRY_ATTEMPTS}, got {self.max_attempts}"
            )
        if not 0.0 <= self.deadline_s <= MAX_RETRY_DEADLINE_S:
            raise ValueError(
                f"deadline_s must be within 0..{MAX_RETRY_DEADLINE_S} s, got {self.deadline_s}"
            )
        if not self.backoff_s or any(value < 0 for value in self.backoff_s):
            raise ValueError("backoff_s must be a non-empty tuple of non-negative seconds")


def default_retry_policy() -> AtomicReplaceRetryPolicy:
    """Frozen defaults: Linux-proven transient errnos on POSIX, fail-closed elsewhere."""

    transient_errnos = LINUX_TRANSIENT_ERRNOS if os.name == "posix" else frozenset()
    return AtomicReplaceRetryPolicy(
        transient_errnos=transient_errnos,
        transient_winerrors=frozenset(),
        max_attempts=MAX_RETRY_ATTEMPTS,
        deadline_s=MAX_RETRY_DEADLINE_S,
        backoff_s=DEFAULT_BACKOFF_S,
    )


@dataclass(frozen=True)
class AtomicReplaceResult:
    outcome: str
    attempts: int
    reason: str | None = None
    error: OSError | None = None


# Primitive seams. Tests inject faults at this seam (the sanctioned fault
# injection point); production code must call the public functions below.
def _read_bytes(path: Path) -> bytes:
    return path.read_bytes()


def _replace(src: Path, dst: Path) -> None:
    os.replace(src, dst)


def _is_transient(error: OSError, retry_policy: AtomicReplaceRetryPolicy) -> bool:
    if error.errno is not None and error.errno in retry_policy.transient_errnos:
        return True
    winerror = getattr(error, "winerror", None)
    return winerror is not None and winerror in retry_policy.transient_winerrors


def atomic_write_bytes(path: Path, data: bytes, *, before_replace=None) -> None:
    """Unconditional atomic write: staged same-dir temp file + fsync + replace.

    No compare-and-swap and no retry: any OSError propagates to the caller
    (byte-identical parity with the superseded per-module write bodies).
    Temp-file residue is cleaned on every failure.
    """

    path.parent.mkdir(parents=True, exist_ok=True)
    temp_path: Path | None = None
    try:
        with tempfile.NamedTemporaryFile(
            "wb",
            dir=path.parent,
            prefix=f".{path.name}.tmp-",
            delete=False,
        ) as handle:
            temp_path = Path(handle.name)
            handle.write(data)
            handle.flush()
            os.fsync(handle.fileno())
        if before_replace is not None:
            before_replace()
        _replace(temp_path, path)
    except BaseException:
        if temp_path is not None:
            with suppress(FileNotFoundError):
                temp_path.unlink()
        raise


def atomic_write_text(path: Path, text: str) -> None:
    atomic_write_bytes(path, text.encode("utf-8"))


def atomic_replace_if_unchanged(
    path: Path,
    expected_identity: bytes,
    new_bytes: bytes,
    retry_policy: AtomicReplaceRetryPolicy,
    *,
    _sleep=time.sleep,
) -> AtomicReplaceResult:
    """Atomically replace ``path`` with ``new_bytes`` while the identity holds.

    Implements the frozen four-outcome semantics documented in the module
    docstring. ``expected_identity`` is re-verified before every attempt; the
    replace is followed by an exact byte readback.
    """

    start = time.monotonic()
    attempt = 0
    while True:
        attempt += 1
        # Re-verify the expected identity before EVERY attempt.
        try:
            current = _read_bytes(path)
        except OSError as exc:
            return AtomicReplaceResult(OUTCOME_UNKNOWN, attempt, REASON_TARGET_UNREADABLE, exc)
        # Current bytes already equal the new bytes: success, never replay.
        if current == new_bytes:
            return AtomicReplaceResult(
                OUTCOME_REPLACED_VERIFIED, attempt, REASON_ALREADY_NEW_NO_REPLAY
            )
        if current != expected_identity:
            return AtomicReplaceResult(OUTCOME_EXTERNAL_CHANGE, attempt)
        try:
            atomic_write_bytes(path, new_bytes)
        except OSError as exc:
            if _is_transient(exc, retry_policy):
                within_budget = (
                    attempt < retry_policy.max_attempts
                    and (time.monotonic() - start) < retry_policy.deadline_s
                )
                if within_budget:
                    _sleep(
                        retry_policy.backoff_s[
                            min(attempt - 1, len(retry_policy.backoff_s) - 1)
                        ]
                    )
                    continue
                return AtomicReplaceResult(
                    OUTCOME_OLD_VERIFIED_RETRYABLE,
                    attempt,
                    REASON_RETRY_BUDGET_EXHAUSTED,
                    exc,
                )
            return AtomicReplaceResult(
                OUTCOME_UNKNOWN, attempt, REASON_REPLACE_FAILED_NON_TRANSIENT, exc
            )
        # Exact bytes readback after the replace.
        try:
            readback = _read_bytes(path)
        except OSError as exc:
            return AtomicReplaceResult(OUTCOME_UNKNOWN, attempt, REASON_READBACK_FAILED, exc)
        if readback != new_bytes:
            return AtomicReplaceResult(OUTCOME_UNKNOWN, attempt, REASON_READBACK_MISMATCH)
        return AtomicReplaceResult(OUTCOME_REPLACED_VERIFIED, attempt)


def _changed_after_read_error(path: Path) -> LockBusyError:
    return LockBusyError(
        f"Refusing to write {path} because the file changed after it was read."
    )


def _raise_for_non_success(path: Path, result: AtomicReplaceResult) -> None:
    if result.outcome == OUTCOME_EXTERNAL_CHANGE:
        raise _changed_after_read_error(path)
    if result.error is not None:
        raise result.error
    raise LockBusyError(
        f"Refusing to continue because {path} changed during post-write verification."
    )


def _read_text(path: Path) -> str:
    return path.read_bytes().decode("utf-8")


def _cas_existing_file(path: Path, *, expected_text: str, new_text: str) -> AtomicReplaceResult:
    current_text = _read_text(path)
    if current_text != expected_text:
        raise _changed_after_read_error(path)
    return atomic_replace_if_unchanged(
        path,
        expected_text.encode("utf-8"),
        new_text.encode("utf-8"),
        default_retry_policy(),
    )


def atomic_write_if_unchanged(path: Path, *, expected_text: str, new_text: str) -> None:
    """Text-level parity wrapper over the CAS primitive (legacy LockBusyError)."""

    if not path.exists():
        if expected_text != "":
            raise _changed_after_read_error(path)
        atomic_write_text(path, new_text)
        return
    result = _cas_existing_file(path, expected_text=expected_text, new_text=new_text)
    if result.outcome == OUTCOME_REPLACED_VERIFIED:
        return
    _raise_for_non_success(path, result)


def atomic_write_and_verify_if_unchanged(
    path: Path,
    *,
    expected_text: str,
    new_text: str,
) -> None:
    """Bound a helper-owned atomic replace to exact before/after text snapshots."""

    if not path.exists():
        if expected_text != "":
            raise _changed_after_read_error(path)
        atomic_write_text(path, new_text)
        _verify_text_readback(path, new_text)
        return
    result = _cas_existing_file(path, expected_text=expected_text, new_text=new_text)
    if result.outcome == OUTCOME_REPLACED_VERIFIED:
        # The primitive's post-replace readback is the exact-bytes verification.
        return
    if result.outcome == OUTCOME_UNKNOWN and result.reason == REASON_READBACK_FAILED:
        if isinstance(result.error, FileNotFoundError):
            raise LockBusyError(
                f"Refusing to continue because {path} disappeared after the helper write."
            ) from result.error
    if result.outcome == OUTCOME_UNKNOWN and result.reason == REASON_READBACK_MISMATCH:
        raise LockBusyError(
            f"Refusing to continue because {path} changed during post-write verification."
        )
    _raise_for_non_success(path, result)


def _verify_text_readback(path: Path, new_text: str) -> None:
    try:
        verified_text = _read_text(path)
    except FileNotFoundError as exc:
        raise LockBusyError(
            f"Refusing to continue because {path} disappeared after the helper write."
        ) from exc
    if verified_text != new_text:
        raise LockBusyError(
            f"Refusing to continue because {path} changed during post-write verification."
        )
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall