duckdb-differential: Instructions file for Codex

Project instructions

• Target DuckDB v2.0.0 (the community repository's current stable; pinned to commit d54cbbe3df, which the community repository builds as v2.0.0, until the tag exists). One C++ extension on DuckDB's C++ extension template, native storage semantics. Linux and macOS (Apple silicon) only.
• All S3 operations must use the AWS SDK for C++ pinned through vcpkg (VCPKG_COMMIT).
• Preserve native sync/namespace ordering, durable mappings, and all retention roots.
• Never perform persistent management actions during bind or planning. The one approved exception: an AT (...) clause opens a hidden read-only snapshot attachment and takes its reader pin at bind time. Do not extend it to identities, snapshots or exports.
• Use only disposable directories and provider namespaces for destructive tests.
• Record actual commands/results in private, untracked implementation notes; distinguish passed probes from full acceptance criteria and untested guarantees.
• Preserve unrelated user edits.
• Do not adopt a core patch, fork, daemon, or weaker durability without a product decision.
• Credentials come from DuckDB TYPE s3 secrets, a named profile or the AWS SDK chain. Never accept them as ATTACH or function options, and never write them anywhere (metadata store, descriptors, heads, listings, status, errors). Commit only when asked.

Product decisions in force

Each decision was made by the repository owner; changing one needs the owner's agreement.

• Native-equivalent durability. Writes go to an overlay and the file group's append-only segment, and are durable at native FileSync (segment fsync, then SQLite FULL with fsync, on every OS as native DuckDB; macOS included, no F_FULLFSYNC: owner decision 2026-10-19).
• Store format 2 (2026-10-19). Payload moved out of SQLite into append-only segments that are also the write journal; 256 KiB block-aligned chunks; WAL sidecars stored as byte ranges; CRC32C verifies local reads (SHA-256 stays the identity and the S3 checksum); exports are differential-export-v2/DIX2. One format revision ahead of WAL shipping.
• Local eviction. The local copy of a completed S3 export may be evicted; reads then go through S3, and branch/clone/restore rehydrate.
• SQL surface. The surface is DuckLake-aligned, and the old functions were replaced outright, with no aliases. Time travel addresses public snapshots, not individual commits. Snapshot on every checkpoint is opt-in.
• Catalog functions and AT. Catalog-scoped functions and AT time travel are provided, with bind-time reader pins. A TYPE differential secret was not adopted.