Skip to content

AI_CONTEXT.MD

Latest commit

 

History

History
71 lines (62 loc) · 3.08 KB

AI_CONTEXT.MD

File metadata and controls

71 lines (62 loc) · 3.08 KB

AI CONTEXT

PURPOSE

CODEXSYNC IS A LOCAL CLI UTILITY FOR COLD-SYNCING CODEX STATE BETWEEN TWO PERSONAL MACHINES THROUGH A SYNCHRONIZED FOLDER.

GOAL

ALLOW DEVELOPERS TO CONTINUE WORK ON A SECOND MACHINE WITHOUT LOSING CODEX LOCAL CONTEXT.

CORE ASSUMPTIONS

  • SYNC RUNS ONLY WHEN CODEX IS FULLY CLOSED.
  • ONLY ONE ACTIVE MACHINE IS USED AT A TIME.
  • THE USER IS RESPONSIBLE FOR CLOUD SYNC READINESS AND AVAILABLE STORAGE CAPACITY.
  • THE PROJECT DOES NOT USE CODEX APIS AND DOES NOT INTERFERE WITH CODEX RUNTIME INTERNALS.

TARGET PLATFORMS AND VERSIONS

  • PYTHON: 3.11+ (MINIMUM SUPPORTED VERSION, MATCHES pyproject.toml).
  • WINDOWS: WINDOWS 10+.
  • MACOS:
    • OFFICIALLY CONFIRMED: CODEX APP IS AVAILABLE ON MACOS (APPLE SILICON).
    • ARCHITECTURE CONSTRAINT: INTEL MAC IS NOT TREATED AS A TARGET PLATFORM.
    • MINIMUM MACOS VERSION IS NOT EXPLICITLY FIXED IN PUBLIC DOCS; UNTIL SEPARATE VALIDATION, TARGET MACOS 14+ ON APPLE SILICON (WORKING ASSUMPTION).
  • LINUX: FUTURE SUPPORT IS POSSIBLE, BUT VERSIONS ARE NOT FIXED UNTIL OFFICIAL CODEX LINUX AVAILABILITY.

CI COVERAGE

  • CI RUNNERS: WINDOWS-LATEST, MACOS-LATEST.
  • LINUX CI IS INTENTIONALLY DISABLED IN MVP.

RUN MODES

  • DIRECT RUN: MANUAL (PYTHON ... OR PACKAGED BINARY).
  • CONFIG BOOTSTRAP: INIT-CONFIG GENERATES config.toml FROM THE TEMPLATE BUNDLED INSIDE THE PYPI PACKAGE.
  • DIAGNOSTIC RUN: DOCTOR/PREFLIGHT TO VALIDATE ENVIRONMENT READINESS BEFORE SYNC.
  • SCHEDULED RUN:
    • WINDOWS: TASK SCHEDULER.
    • MACOS: LAUNCHD (LAUNCHAGENT) OR EQUIVALENT SCHEDULED JOB.
  • FOR WINDOWS, PACKAGING THE PYTHON SCRIPT INTO .EXE (FOR EXAMPLE VIA PYINSTALLER) IS ALLOWED TO SIMPLIFY DEPLOYMENT.

MVP FEATURES

  1. DETECT CODEX PROCESS (WINDOWS AT MINIMUM, WITH MACOS EXTENSION).
  2. DETECT CODEX STATE DIRECTORY.
  3. COMPARE LOCAL AND CLOUD COPIES.
  4. SYNC CHANGES.
  5. ENFORCE BACKUP BEFORE OVERWRITE.
  6. EXCLUDE TEMP/LOCK/CACHE FILES.

SAFETY CRITERIA

  • NEVER WRITE TO STATE WHILE CODEX IS RUNNING.
  • ALWAYS CREATE A BACKUP BEFORE OVERWRITE.
  • ON UNCERTAINTY, FAIL-SAFE (ABORT WITHOUT WRITES).

RECORDED DECISIONS

  • CONFLICT POLICY: IF BOTH SIDES CHANGED, TREAT AS CONFLICT, DO NOT SYNC, PRINT CONFLICT FILE LIST, AND EXIT.
  • CONFLICT RESOLUTION: MANUAL BY USER; RERUN REQUIRED AFTER MANUAL RESOLUTION.
  • LOGGING:
    • LEVELS: DEBUG|INFO|WARNING|ERROR.
    • FORMATS: TEXT|JSON|LOGFMT (CONFIGURABLE).
    • ROTATION: RETENTION-BASED, DEFAULT 7 DAYS.
  • FILE-TIME NORMALIZATION: NO DEDICATED NORMALIZATION/CLOCK COMPENSATION IN MVP; RELY ON OS/FILESYSTEM TIMESTAMPS.
  • PREFLIGHT/DOCTOR CHECKS:
    • CONFIG + RUNTIME PATH READINESS.
    • WRITE ACCESS PROBES FOR LOCAL/CLOUD/BACKUP/TEMP ROOTS.
    • CODEX PROCESS SAFETY PRECONDITION.
    • MANIFEST DATA-VERSION COMPATIBILITY.
    • SUSPICIOUS LOCAL/CLOUD PROBE MTIME DRIFT (WARNING SIGNAL).
    • ORPHAN TEMP FILE DETECTION.
  • CLI EXIT CODES (FOR CI/AUTOMATION):
    • 0 SUCCESS (INCLUDING NO-OP).
    • 1 RUNTIME ERROR.
    • 2 CONFLICTS DETECTED, MANUAL RESOLUTION REQUIRED.
    • 3 CODEX IS RUNNING, SYNC BLOCKED.
    • 4 CONFIG OR ARGUMENT ERROR.
    • 5 SAFE ABORT (FAIL-SAFE) DUE TO UNCERTAIN STATE.