ferro-orm 0.3.4__tar.gz → 0.5.0__tar.gz

ferro_orm-0.5.0/.context/compound-engineering/ce-code-review/20260428-081705-bdeab5a2/agent-native.json

@@ -0,0 +1,87 @@
+{
+  "reviewer": "agent-native",
+  "summary": "ferro is a programmatic Python ORM; the library itself IS the agent-native surface (no UI, no MCP/agent-tool layer in this PR). The ForeignKey(index=True) addition is well-documented for AI agents generating ferro models: the new `index` parameter is exposed via __init__ kwarg, listed in the class Attributes block, covered by Args with a runnable doctest example, propagated into the JSON schema for downstream introspection (Alembic + Rust runtime both consume it), and noted in CHANGELOG + docs/guide/relationships.md. Action parity, context parity, and shared-workspace checks are not applicable to a library API of this shape. Two concrete agent-discoverability nits in the JSON schema serialization layer, plus a residual operational risk (Alembic vs Rust runtime index name divergence) worth surfacing.",
+  "capability_map": [
+    {
+      "capability": "Declare non-unique index on FK shadow column",
+      "human_path": "ForeignKey(index=True) kwarg, documented in docstring + relationships.md",
+      "agent_path": "Same kwarg; signature, defaults, and warning behavior are introspectable via inspect.signature() and the class docstring",
+      "in_prompt_or_docstring": true,
+      "priority": "must_have",
+      "status": "parity"
+    },
+    {
+      "capability": "Detect that a FK column is indexed via schema metadata",
+      "human_path": "model_json_schema() returns prop['index']=True for indexed FK columns",
+      "agent_path": "Asymmetric: non-FK FerroField columns always carry an explicit `index` key (True or False); FK columns only carry `index` when True. Also, the `foreign_key` sub-dict embeds `unique` but not `index`",
+      "in_prompt_or_docstring": false,
+      "priority": "should_have",
+      "status": "minor_gap"
+    },
+    {
+      "capability": "Discover effective index name across migration backends",
+      "human_path": "docs/guide/relationships.md explicitly states Alembic emits ix_<t>_<c> while Rust runtime emits idx_<t>_<c>",
+      "agent_path": "Docstring on ForeignKey.index does not surface this divergence; an agent that only reads the docstring would not learn the dual-naming convention",
+      "in_prompt_or_docstring": false,
+      "priority": "low",
+      "status": "observation"
+    }
+  ],
+  "findings": [
+    {
+      "title": "FK index flag asymmetric in JSON schema vs FerroField",
+      "severity": "P3",
+      "file": "src/ferro/schema_metadata.py",
+      "line": 132,
+      "why_it_matters": "Downstream agents and tools that inspect ferro's JSON schema to reason about FK indexes have to special-case absence-as-false for FK columns while non-FK columns always carry an explicit `index` boolean. An agent computing 'which FK columns lack indexes?' from the schema cannot rely on key presence -- it must default-coerce -- and the inconsistency invites bugs in autogen tooling that round-trips schemas. Minor agent-introspection contract drift.",
+      "autofix_class": "safe_auto",
+      "owner": "review-fixer",
+      "requires_verification": true,
+      "suggested_fix": "Replace `if metadata.index: prop['index'] = True` with `prop['index'] = metadata.index` so FK columns always carry an explicit index boolean, matching the FerroField branch on line 107.",
+      "confidence": 75,
+      "evidence": [
+        "src/ferro/schema_metadata.py:107 — `prop['index'] = metadata.index` (unconditional for FerroField)",
+        "src/ferro/schema_metadata.py:132-133 — `if metadata.index: prop['index'] = True` (conditional for ForeignKey, only set when truthy)"
+      ],
+      "pre_existing": false
+    },
+    {
+      "title": "foreign_key descriptor dict omits index flag",
+      "severity": "P3",
+      "file": "src/ferro/schema_metadata.py",
+      "line": 125,
+      "why_it_matters": "The `prop['foreign_key']` sub-dict is the natural place for an agent to look up everything FK-related on a column (to_table, on_delete, unique are all there). The new `index` flag is set on the peer property instead, so any agent or external tool that reads `prop['foreign_key']` to enumerate FK-specific config will silently miss the index flag and have to know to also peek at the sibling. This makes the FK descriptor a lossy view of FK metadata.",
+      "autofix_class": "safe_auto",
+      "owner": "review-fixer",
+      "requires_verification": true,
+      "suggested_fix": "Add `\"index\": metadata.index` to the `prop['foreign_key']` dict alongside `unique`, in addition to (or instead of) the peer `prop['index']` write. Keeps FK metadata co-located for agent introspection.",
+      "confidence": 75,
+      "evidence": [
+        "src/ferro/schema_metadata.py:125-129 — foreign_key dict includes to_table/on_delete/unique but not index",
+        "src/ferro/schema_metadata.py:132-133 — index is set as a peer property only"
+      ],
+      "pre_existing": false
+    }
+  ],
+  "residual_risks": [
+    "Alembic vs Rust runtime DDL emit different index names for the same FK column (ix_<table>_<col> vs idx_<table>_<col>). An agent that runs `connect(..., auto_migrate=True)` once and later switches to Alembic-driven migrations could end up with two real indexes on the same column (Alembic autogen sees no ix_* and creates one). Documented in docs/guide/relationships.md but not in the ForeignKey.index docstring; agents generating ferro models from the docstring alone would not learn this.",
+    "ForeignKey(unique=True, index=True) silently mutates self.index to False after issuing a UserWarning. An agent that constructs the ForeignKey programmatically and later introspects `fk.index` sees the effective post-init state, not the originally-passed value. The warning makes the override visible in interactive runs but not in non-interactive agent flows that may filter or suppress warnings.",
+    "FerroField.unique does not state that it implies an index, while ForeignKey.unique now does. Pre-existing inconsistency in agent-facing documentation; out of scope for this PR but worth surfacing for a future docstring sweep."
+  ],
+  "testing_gaps": [
+    "No test asserts the JSON schema shape for FK index — i.e., that prop['index'] (or prop['foreign_key']['index']) is present on the schema dict produced by build_model_schema. Current tests only assert the SQLAlchemy metadata side (project_table.c.org_id.index) and the Rust DDL output. If the asymmetry above is fixed, a schema-shape regression test would prevent it recurring.",
+    "No test exercises ForeignKey(unique=True, index=True) at the schema-metadata layer -- only at the Python-class layer. A test asserting that the resulting prop carries unique=True and index=False (effective config) would lock in the documented warning behavior end-to-end."
+  ],
+  "score": {
+    "high_priority_capabilities_with_agent_parity": "1/1",
+    "verdict": "PASS"
+  },
+  "whats_working_well": [
+    "ForeignKey.index is fully discoverable via standard Python introspection: kwarg in __init__ signature, listed in class-level Attributes, covered in Args with a runnable doctest, and reflected on the instance as self.index.",
+    "The docstring explicitly documents the unique+index redundancy and the resulting UserWarning, so an agent generating models will not be surprised by silent normalization.",
+    "stacklevel=2 on the warnings.warn call points at the user's call site, not ferro internals -- correct for agent log triage.",
+    "Schema metadata propagates the flag to both Alembic and the Rust DDL path, keeping the two code-generation backends in sync from a single declarative source.",
+    "CHANGELOG entry references the issue (#32) and explicitly calls out the warning behavior, giving agents a single canonical pointer to the new flag's contract.",
+    "src/ferro/_core.pyi correctly does not need updating -- ForeignKey is a pure-Python class; type checkers pick up the signature directly from base.py."
+  ]
+}

ferro_orm-0.5.0/.context/compound-engineering/ce-code-review/20260428-081705-bdeab5a2/api-contract.json

@@ -0,0 +1,40 @@
+{
+  "reviewer": "api-contract",
+  "findings": [
+    {
+      "id": "api-contract-1",
+      "title": "New `index` parameter inserted positionally before `nullable` silently rebinds 4th positional arg",
+      "severity": "high",
+      "confidence": 75,
+      "file": "src/ferro/base.py",
+      "lines": "114-120",
+      "category": "breaking-change",
+      "description": "`ForeignKey.__init__` is a public, exported API (re-exported from `ferro/__init__.py`). The new `index: bool = False` is inserted between `unique` and `nullable` as a regular positional-or-keyword parameter; none of the existing parameters are keyword-only (no `*` separator). Any external caller passing arguments positionally past `unique` silently rebinds. Concrete breakage examples for callers upgrading without source changes:\n\n- `ForeignKey(\"posts\", \"CASCADE\", False, True)` previously meant `nullable=True`; now means `index=True` and `nullable` falls back to `'infer'`. The shadow `*_id` column's NOT NULL behavior can flip from forced-NULL to inferred-from-annotation, and an unintended index is emitted.\n- `ForeignKey(\"posts\", \"CASCADE\", False, \"infer\")` previously a no-op nullable hint; now sets `self.index = 'infer'` (a non-bool truthy string). `metadata.index` is then truthy in `schema_metadata.py`, producing `prop['index'] = True` and an unintended `CREATE INDEX`. Type contract for `index: bool` is also violated without validation.\n- `ForeignKey(\"posts\", \"CASCADE\", True, True)` previously meant `unique=True, nullable=True`; now means `unique=True, index=True` -> the new redundancy warning fires (`UserWarning`) and `nullable` silently changes to `'infer'`.\n\nAll in-tree call sites use keyword arguments (verified across `src/`, `tests/`, `docs/`, `scripts/`), so the project itself is unaffected — but `ForeignKey` is part of the documented public API and the contract on positional ordering changed.",
+      "evidence": "diff src/ferro/base.py:\n    def __init__(\n        self,\n        related_name: str,\n        on_delete: str = \"CASCADE\",\n        unique: bool = False,\n        index: bool = False,        # <-- inserted between unique and nullable\n        nullable: FerroNullable = \"infer\",\n    ):\nNo `*,` separator, so positional binding order changes. `self.index` is also assigned the raw value with no type validation (contrast `_validate_nullable_option`).",
+      "suggested_fix": "Make `index` (and ideally `unique` and `nullable`, since they are clearly intended as kwargs) keyword-only by adding `*,` before `unique` (least disruptive) or at minimum before `index`:\n\n```python\ndef __init__(\n    self,\n    related_name: str,\n    on_delete: str = \"CASCADE\",\n    *,\n    unique: bool = False,\n    index: bool = False,\n    nullable: FerroNullable = \"infer\",\n):\n```\n\nThis preserves the only realistic positional call shape (`ForeignKey(\"posts\", \"CASCADE\")`) and makes the contract robust to future insertions. It also matches how every example in the codebase already calls it. If a softer landing is preferred for v0.x, at minimum insert `*,` immediately before `index` so additions never reorder existing positional semantics again, and add an `isinstance(index, bool)` guard to reject the non-bool truthy case."
+    },
+    {
+      "id": "api-contract-2",
+      "title": "Serialized model schema gains a new optional `index` key on FK columns — additive but worth documenting",
+      "severity": "low",
+      "confidence": 50,
+      "file": "src/ferro/schema_metadata.py",
+      "lines": "131-134",
+      "category": "schema-contract",
+      "description": "`build_model_schema` now writes `prop['index'] = True` on FK column entries when `metadata.index` is truthy, conditionally (matching the existing pattern for `prop['unique']`). This JSON schema is consumed by the Rust core (`register_model_schema`) and is part of the cross-language contract. The change is additive: the key is absent when `index=False` and consumers using `dict.get('index', False)` are safe. Two consumer expectations to confirm before declaring this fully safe:\n\n1. The Rust `schema.rs` parsing path tolerates an unknown-to-old-binaries `index` key on FK column dicts — the in-PR Rust test confirms it does, so OK.\n2. Any out-of-tree tooling that snapshots/diffs the serialized schema (autogen baselines, golden files) will see a new key on FK columns whenever a user opts into `index=True`. Not breaking, but PRs touching schema serialization should call this out in CHANGELOG so external integrators know to refresh fixtures. CHANGELOG already mentions the feature; could note the schema-key addition explicitly.\n\nThe `foreign_key` sub-dict shape is unchanged (`to_table`, `on_delete`, `unique`), which is the right call — keeping `index` as a column-level flag rather than nesting it under `foreign_key` matches how `FerroField(index=True)` already serializes.",
+      "evidence": "src/ferro/schema_metadata.py:\n    if metadata.unique:\n        prop[\"unique\"] = True\n    if metadata.index:\n        prop[\"index\"] = True\nRust test in src/schema.rs asserts `idx_<table>_<col>` is emitted when `index: true` is set on an FK column — Rust side handles it.",
+      "suggested_fix": "No code change required. Optionally add a one-line note in the Unreleased CHANGELOG entry that the JSON schema now carries an optional `index` boolean on FK column properties, so downstream tooling that pins or snapshots the schema is aware."
+    }
+  ],
+  "residual_risks": [
+    "`_core.pyi` does not declare `ForeignKey` or `build_model_schema` (only Rust-extension async functions), so no .pyi update is required. Confirmed via Grep — no false-positive 'missing stub' risk.",
+    "Public `ForeignKey` instances now carry a new `.index` attribute. This is purely additive for introspection consumers (`hasattr(fk, 'index')` flips from False to True). Anyone iterating `vars(fk)` for serialization will see the new key. Not a contract break, but worth noting if any external Alembic env.py or migration helper enumerates FK attributes.",
+    "The `unique=True, index=True` UserWarning + silent drop is a defensible behavior choice, but it is a *new* runtime warning surface. Strict warning filters (`warnings.simplefilter('error')`) in user test suites would now raise on this combination. Since `index` is a new parameter, no pre-existing code can hit this path on upgrade — risk is forward-only and only for users who explicitly opt into both flags.",
+    "Type contract on the `index` parameter is unenforced — `self.index` accepts any truthy value (including the `'infer'` literal that's valid for `nullable`). Combined with the positional-rebinding risk in finding api-contract-1, a misplaced positional argument can poison the schema with a non-bool. An `isinstance(index, bool)` validator (or relying on the keyword-only fix) would close this."
+  ],
+  "testing_gaps": [
+    "No test exercises the positional-argument call shape (e.g., `ForeignKey('posts', 'CASCADE', False, True)`) to lock in the *intended* binding for `index` vs `nullable`. Adding either (a) a test that asserts the keyword-only nature of `index` (e.g., `with pytest.raises(TypeError): ForeignKey('x', 'CASCADE', False, True, 'infer')` after the fix) or (b) a regression test pinning the current positional contract would prevent silent reordering in future PRs.",
+    "No test asserts that passing a non-bool to `index` is rejected or coerced. With the current code, `ForeignKey('x', index='infer')` silently assigns the string and produces `prop['index'] = True` downstream. A small input-validation test (alongside the existing `_validate_nullable_option` pattern) would harden the contract.",
+    "No test covers the JSON schema shape for the FK-with-index case at the Python boundary (the existing tests assert SQLAlchemy `Column.index` is True and the Rust DDL contains `idx_*`, but not that `build_model_schema(...)['properties']['org_id']` contains exactly `{'foreign_key': {...}, 'index': True, ...}` and crucially does NOT contain `'index': False` when off). This locks the wire-format contract to Rust."
+  ]
+}

ferro_orm-0.5.0/.context/compound-engineering/ce-code-review/20260428-081705-bdeab5a2/correctness.json

@@ -0,0 +1,15 @@
+{
+  "reviewer": "correctness",
+  "summary": "Traced every input/state path for the ForeignKey(index=True) feature: constructor → schema_metadata.build_model_schema → Alembic _build_sa_table and Rust schema.rs emission. No correctness defects identified. The default (index=False) path is bit-for-bit identical to the prior behavior because `if metadata.index:` guards the new prop assignment, and both downstream emitters already read `col_info.get('index', False)` / `column_bool_metadata(..., 'index').unwrap_or(false)`. The unique+index overlap is collapsed in __init__ before the schema layer ever sees it, so neither Alembic nor Rust can double-emit a unique constraint and a redundant index. Naming convention parity (Alembic `ix_project_org_id` from SA's default; Rust `idx_project_org_id` from format!(\"idx_{}_{}\")) is asserted by both Python and Rust tests. IF NOT EXISTS in the Rust path keeps re-runs idempotent.",
+  "findings": [],
+  "residual_risks": [
+    "If a user passes ForeignKey(unique=True, index=True, nullable='bogus'), the redundancy UserWarning is emitted *before* _validate_nullable_option raises, leaving a leaked warning for an object that never finished construction. Pure UX nit — not a correctness bug — and below the flagging threshold. Constructor-order swap (validate first, then warn-and-drop) would eliminate it.",
+    "Rust DDL parity test runs only on SQLite (sqlite_only marker). Postgres parity is covered by the new schema.rs unit test, not an end-to-end migration test, so a future regression in the auto_migrate Postgres path could land without a failing pytest. Existing residual risk pattern, not introduced by this PR.",
+    "Adding index=True to an existing FK on a deployed model will cause Alembic autogen to produce an op.create_index migration. That is the intended feature, but operators applying it to a large hot table should be aware (CREATE INDEX is non-concurrent by default in Postgres). Documented behavior, not a code defect."
+  ],
+  "testing_gaps": [
+    "No test covers an explicit ForeignKey(unique=False, index=False) round-trip asserting that the JSON schema for the shadow column does *not* contain an 'index' key (only that SA Column.index is False). The current `if metadata.index:` guard preserves this, but a schema-level assertion would lock it in against future refactors that set prop['index'] = metadata.index unconditionally (which would change the JSON shape consumed by the Rust side and any downstream consumers).",
+    "No test exercises the Rust DDL path on Postgres for ForeignKey(index=True) end-to-end (only the SQLite runtime parity test and the in-process Rust unit test). A connected Postgres integration test asserting pg_indexes contains idx_project_org_id would close the loop.",
+    "No test for the case where ForeignKey(index=True) is combined with on_delete='SET NULL' AND the relation annotation is non-Optional (e.g., `Annotated[Org, ForeignKey(on_delete='SET NULL', index=True)]`). The existing nullable-validation path raises ValueError in __init__, but the index kwarg is set on self before validation runs; if construction fails the instance is discarded so this is benign, but a focused negative test would document the precedence."
+  ]
+}

ferro_orm-0.5.0/.context/compound-engineering/ce-code-review/20260428-081705-bdeab5a2/data-migrations.json

@@ -0,0 +1,72 @@
+{
+  "reviewer": "data-migrations",
+  "findings": [
+    {
+      "id": "fk-index-docs-missing-concurrently-warning",
+      "severity": "medium",
+      "confidence": 70,
+      "title": "Docs steer users toward index=True on hot tenant tables but never warn that Alembic autogen emits a blocking CREATE INDEX",
+      "where": "docs/guide/relationships.md \"Indexing FK columns\" section (added in this PR)",
+      "summary": "The new docs explicitly position ForeignKey(index=True) for the exact workload where naive autogen output is most dangerous: \"tenant-scoped tables that filter by a FK on every read\". With index=True set on a model, Alembic autogen against a populated production DB will emit op.create_index(...) which compiles to plain CREATE INDEX on Postgres. CREATE INDEX (without CONCURRENTLY) takes ACCESS EXCLUSIVE on the table for the duration of the build, which on a hot tenant table means writes are blocked for seconds-to-minutes. There is no mention of postgresql_concurrently=True, no mention of editing the autogen output before applying, and no mention that the wrapping transaction must be disabled when using CONCURRENTLY (Alembic op.execute('COMMIT') / transaction_per_migration / autocommit_block).",
+      "evidence": [
+        "docs/guide/relationships.md adds: \"Postgres does not auto-index foreign-key columns, so tenant-scoped tables that filter by a FK on every read should declare the index on the model\" and shows a Project(org=ForeignKey(..., index=True)) example.",
+        "src/ferro/migrations/alembic.py:182-187 passes index=col_info.get('index', False) into sa.Column kwargs. Autogen will diff against the live DB and emit op.create_index(...). There is no override of the rendered op and no naming-convention-driven hint about CONCURRENTLY.",
+        "CHANGELOG.md entry markets the feature without operational caveats."
+      ],
+      "impact": "First user to add index=True to a populated production tenant table (the documented use case) and run alembic upgrade head will block writes on that table for the duration of the index build. Recoverable but classic Postgres outage pattern.",
+      "remediation": "Add an admonition to docs/guide/relationships.md (Indexing FK columns) that says, on Postgres, populated tables should hand-edit the generated migration to use op.create_index(..., postgresql_concurrently=True) inside an autocommit_block (and remove the index= kwarg from op.create_table flows / use op.create_index separately), and that this cannot run inside a wrapping transaction. Optionally add the same caveat to the CHANGELOG entry."
+    }
+  ],
+  "residual_risks": [
+    {
+      "id": "fk-index-name-divergence-double-create",
+      "severity": "medium",
+      "confidence": 65,
+      "title": "Alembic 'ix_<table>_<col>_id' vs Rust runtime 'idx_<table>_<col>_id' will create two indexes on the same column for users who run both auto_migrate and Alembic",
+      "where": "src/ferro/migrations/alembic.py:44 (sa.MetaData() created with no naming_convention) and the Rust idx_* prefix exercised in the new tests",
+      "summary": "ferro.migrations builds sa.MetaData() with no naming_convention, so sa.Column('org_id', ..., index=True) inherits SQLAlchemy's default 'ix_<table>_<col>' index name (i.e. ix_project_org_id). The Rust runtime DDL emits idx_project_org_id (verified by the new tests/test_schema_constraints.py::test_foreign_key_index_runtime_ddl_parity and the new src/schema.rs unit test). For a user who first calls connect(auto_migrate=True) (creating idx_project_org_id) and later runs alembic revision --autogenerate, Alembic's reflection sees an index named idx_project_org_id but the model-side metadata wants ix_project_org_id; autogen will emit a CreateIndex(ix_project_org_id) op, leaving the database with two physically-identical indexes on the same column under different names. The reverse order (Alembic first, auto_migrate second) is also problematic: the Rust path will attempt to create idx_* on top of the existing ix_*. As the PR description acknowledges, this is the same divergence already present for FerroField(index=True); this PR widens the surface from 'user-declared singleton indexes' to 'every FK column the user opts into', which is a much more common case in real apps.",
+      "evidence": [
+        "src/ferro/migrations/alembic.py:44 — metadata = sa.MetaData()  (no naming_convention dict).",
+        "src/ferro/migrations/alembic.py:186 — kwargs['index'] = col_info.get('index', False) → SA emits ix_<table>_<col>.",
+        "tests/test_schema_constraints.py::test_foreign_key_index_runtime_ddl_parity asserts 'idx_project_org_id' in sqlite_master.",
+        "src/schema.rs new unit test asserts joined.contains(\"IDX_PROJECT_ORG_ID\")."
+      ],
+      "impact": "Silent duplicate indexes on tenant FK columns: 2x write amplification on every INSERT/UPDATE of the table, 2x storage. Does not cause data loss or query incorrectness; degrades the exact workload (hot tenant tables) the feature is sold for.",
+      "remediation": "Out of scope for this PR if the team has already accepted the existing FerroField(index=True) divergence, but worth tracking as a follow-up: align both paths on a single naming scheme by setting a naming_convention={'ix': 'idx_%(table_name)s_%(column_0_label)s'} on sa.MetaData() in src/ferro/migrations/alembic.py so SA emits idx_* names matching the Rust runtime."
+    },
+    {
+      "id": "fk-index-redundant-with-composite-leftmost-prefix",
+      "severity": "low",
+      "confidence": 55,
+      "title": "ForeignKey(index=True) does not detect / dedupe against a composite index whose leftmost column is the same FK shadow column",
+      "where": "src/ferro/schema_metadata.py build_model_schema and src/ferro/composite_indexes.py warn_and_drop_overlap_with_uniques",
+      "summary": "warn_and_drop_overlap_with_uniques only deduplicates ferro_composite_indexes against ferro_composite_uniques. There is no equivalent check for the new per-column FK index against ferro_composite_indexes that already cover the same column as their leftmost prefix. A user who declares __ferro_composite_indexes__ = ((\"org_id\", \"created_at\"),) and also adds ForeignKey(\"orgs\", index=True) will get two indexes — idx_<t>_org_id_created_at AND ix_<t>_org_id (Alembic) / idx_<t>_org_id (Rust) — where the first already serves all WHERE org_id = ? queries via Postgres's leftmost-prefix optimization.",
+      "evidence": [
+        "src/ferro/schema_metadata.py:130-133 unconditionally sets prop['index'] = True when metadata.index is True; no cross-check against schema['ferro_composite_indexes'].",
+        "src/ferro/composite_indexes.py warn_and_drop_overlap_with_uniques only handles composite-vs-composite-unique, not single-column-vs-composite-leftmost."
+      ],
+      "impact": "Wasted storage and write amplification on tables that are precisely the high-write tenant tables this feature targets. Not a correctness or migration-safety issue.",
+      "remediation": "Out of scope for this PR. Optional follow-up: extend warn_and_drop_overlap_with_uniques to a generic warn_and_drop_overlap routine that also drops a column-level FK index when an existing composite index has that column as its leftmost prefix, with a UserWarning pointing the user at the composite."
+    }
+  ],
+  "testing_gaps": [
+    {
+      "id": "no-autogen-roundtrip-test",
+      "severity": "low",
+      "confidence": 70,
+      "title": "No test exercises the actual Alembic autogen path (compare_metadata) for ForeignKey(index=True) — only the static MetaData object is asserted",
+      "where": "tests/test_alembic_autogenerate.py (new tests)",
+      "summary": "The four new tests in test_alembic_autogenerate.py inspect get_metadata().tables['project'].c.org_id.index but never run alembic.autogenerate.compare_metadata against a live (or in-memory) DB to verify that the diff actually emits a CreateIndexOp with the expected name and that the same MetaData against an already-indexed DB emits no diff (idempotency). This is the test that would catch the ix_ vs idx_ name divergence regressing into a 'phantom CreateIndex on every autogen run' bug.",
+      "remediation": "Add one test that sets up an empty SQLite DB, runs compare_metadata(MigrationContext, get_metadata()), and asserts an op with type 'add_index' and column 'org_id' appears. Add a second test that pre-creates the index under SA's expected ix_ name and asserts compare_metadata yields no diff."
+    },
+    {
+      "id": "no-pg-runtime-parity-test",
+      "severity": "low",
+      "confidence": 60,
+      "title": "Runtime DDL parity test for ForeignKey(index=True) is sqlite_only; Postgres path is only covered by a Rust unit test",
+      "where": "tests/test_schema_constraints.py::test_foreign_key_index_runtime_ddl_parity",
+      "summary": "The new integration test is marked @pytest.mark.sqlite_only. The Rust unit test in src/schema.rs loops over [SqlDialect::Sqlite, SqlDialect::Postgres] and asserts CREATE INDEX text, but no end-to-end Postgres test verifies the index actually exists in pg_indexes after connect(auto_migrate=True). Given that the documented use case is Postgres tenant tables, a Postgres-side runtime parity test is the highest-value missing coverage.",
+      "remediation": "Mirror the sqlite test as a @pytest.mark.postgres_only test that queries pg_indexes WHERE tablename = 'project' AND indexname = 'idx_project_org_id'."
+    }
+  ]
+}

ferro_orm-0.5.0/.context/compound-engineering/ce-code-review/20260428-081705-bdeab5a2/kieran-python.json

@@ -0,0 +1,44 @@
+{
+  "reviewer": "kieran-python",
+  "findings": [
+    {
+      "id": "kieran-python-1",
+      "title": "Docstring example for ForeignKey(index=True) is not runnable / inconsistent with the public guide",
+      "file": "src/ferro/base.py",
+      "lines": "138-148",
+      "severity": "P1",
+      "category": "maintainability",
+      "confidence": 75,
+      "summary": "The new __init__ docstring example uses Annotated[int, ForeignKey(\"projects\", index=True)] and never defines an Org/Project pair, so a reader cannot copy-paste it into a working module. The user-facing relationships guide (and your own internal pattern) uses Annotated[<TargetModel>, ForeignKey(related_name=\"projects\", index=True)] with the model class as the first type argument; that's how the ForeignKey resolves its `to` target. The doctest also reuses the same int-typed shape that the existing profile_id example uses, perpetuating an example pattern that doesn't reflect real usage. Either define a tiny Org model in the example and use `org: Annotated[Org, ForeignKey(related_name=\"projects\", index=True)]`, or drop the new example block entirely and let the class-level docstring carry one canonical example. The new example is the most likely thing a reader hits via IDE hover, so it should be the most correct, not the most stylized.",
+      "fix_suggestion": "Replace the appended example with a runnable one: `>>> class Org(Model):\\n...     id: Annotated[int, FerroField(primary_key=True)]\\n>>>\\n>>> class Project(Model):\\n...     id: Annotated[int, FerroField(primary_key=True)]\\n...     org: Annotated[Org, ForeignKey(related_name=\"projects\", index=True)]` — matching docs/guide/relationships.md."
+    },
+    {
+      "id": "kieran-python-2",
+      "title": "Four new tests duplicate `from ferro import BackRef, ForeignKey, Relation` inline instead of using the module-level import block",
+      "file": "tests/test_alembic_autogenerate.py",
+      "lines": "195, 214, 238, 256",
+      "severity": "P1",
+      "category": "maintainability",
+      "confidence": 75,
+      "summary": "The file already imports public ferro symbols at module top (`from ferro import FerroField, Model, clear_registry, reset_engine`). The only inline imports prior to this PR are inside the cleanup fixture and pull `ferro.state` *internals* — a deliberate exception. The four new tests instead import public API (`BackRef, ForeignKey, Relation`) inside each function body, four copies of the same line, with no scoping reason. This breaks the existing convention, hides the test file's real surface area when scanning the top of the file, and adds noise to every new test. Hoist the import to the top once.",
+      "fix_suggestion": "Change line 10 to `from ferro import BackRef, FerroField, ForeignKey, Model, Relation, clear_registry, reset_engine` and delete the four inline `from ferro import BackRef, ForeignKey, Relation` lines."
+    },
+    {
+      "id": "kieran-python-3",
+      "title": "Redundancy UserWarning fires before `nullable` is validated, so an invalid `nullable` argument produces both a warning and a TypeError",
+      "file": "src/ferro/base.py",
+      "lines": "150-167",
+      "severity": "P2",
+      "category": "reliability",
+      "confidence": 50,
+      "summary": "`__init__` currently runs in this order: assign attributes -> warn if `unique and index` -> `_validate_nullable_option(nullable, \"ForeignKey\")` -> SET NULL+nullable=False guard. If a caller passes `ForeignKey(..., unique=True, index=True, nullable=\"bogus\")` they get a UserWarning about a redundant flag *and then* a TypeError about nullable. The warning is also issued for an object that fails to construct, polluting filters and pytest.warns scopes. Validate inputs first (nullable, then SET-NULL/nullable interaction), then surface the redundancy warning once we know the FK config is otherwise legal. This also keeps the fast-fail TypeError path uncluttered by warnings noise.",
+      "fix_suggestion": "Reorder to: `_validate_nullable_option` -> SET NULL guard -> redundancy warning + `self.index = False`. Drop the assignment-then-overwrite of `self.index` and assign the final value once."
+    }
+  ],
+  "residual_risks": [
+    "Runtime DDL parity for ForeignKey(index=True) is exercised end-to-end only on SQLite (`@pytest.mark.sqlite_only` in test_foreign_key_index_runtime_ddl_parity). The Rust unit test in src/schema.rs does cover both Sqlite and Postgres dialects, so this is mitigated, but there is no Python-level Postgres integration test confirming the Rust runtime emits `idx_project_org_id` against a real Postgres database; rely on the Rust unit test until a Postgres integration fixture exists."
+  ],
+  "testing_gaps": [
+    "No test asserts the warning text content beyond `match=\"redundant\"`. If the wording is part of the user-facing contract (CHANGELOG and docstring both quote it), consider asserting on the full sentence or at minimum on `\"unique=True\"` + `\"index=True\"` + `\"redundant\"` to lock it in."
+  ]
+}

ferro_orm-0.5.0/.context/compound-engineering/ce-code-review/20260428-081705-bdeab5a2/maintainability.json

@@ -0,0 +1,79 @@
+{
+  "reviewer": "maintainability",
+  "scope": {
+    "branch": "feat/foreign-key-index-32",
+    "pr": 36,
+    "files": [
+      "src/ferro/base.py",
+      "src/ferro/schema_metadata.py",
+      "src/schema.rs",
+      "tests/test_alembic_autogenerate.py",
+      "tests/test_schema_constraints.py",
+      "docs/guide/relationships.md",
+      "CHANGELOG.md"
+    ]
+  },
+  "findings": [
+    {
+      "id": "fk-index-silent-mutation",
+      "title": "ForeignKey.__init__ silently mutates the user-passed `index` attribute on redundancy",
+      "file": "src/ferro/base.py",
+      "lines": "150-162",
+      "category": "naming-clarity / least-surprise",
+      "severity": "low",
+      "confidence": 55,
+      "description": "After `unique=True, index=True`, __init__ emits a UserWarning and resets `self.index = False`. The instance attribute then disagrees with the kwarg the caller passed. Anyone introspecting `fk.index` later (debugging, custom tooling, third-party schema diffing, a future Ferro feature that conditionally branches on `metadata.index`) sees False even though the source code says True. The warning fires once at class-definition time and is then lost; the lie on the attribute persists for the life of the process. This also makes the new test `assert profile_table.c.user_id.index is False` correct only because of the silent mutation -- a future maintainer reading just `ForeignKey(unique=True, index=True)` would reasonably expect `index=True` to round-trip.",
+      "suggestion": "Treat `index` as the literal user intent and compute the *effective* index decision at the single consumer (schema_metadata.py): `if metadata.index and not metadata.unique: prop[\"index\"] = True`. Keep the UserWarning where it is. This (a) preserves the user's input on the metadata object, (b) keeps the redundancy logic in one place, and (c) makes the intent explicit at the consumer site rather than hidden in a constructor side effect. If you do keep the mutation, add an inline comment near `self.index = False` explaining that the public attribute is normalized post-warning, so the next maintainer doesn't read it as a bug.",
+      "user_flagged": true
+    },
+    {
+      "id": "fk-vs-ferrofield-redundancy-asymmetry",
+      "title": "Parallel-but-divergent handling of `unique=True, index=True` between FerroField and ForeignKey",
+      "file": "src/ferro/base.py",
+      "lines": "54-85, 114-167",
+      "category": "api-symmetry / coupling",
+      "severity": "low",
+      "confidence": 60,
+      "description": "ForeignKey now warns + drops `index` when combined with `unique`. FerroField has had `unique` and `index` for longer and silently accepts both; downstream in schema_metadata.py the FerroField path unconditionally writes `prop[\"unique\"] = metadata.unique` AND `prop[\"index\"] = metadata.index` (lines 106-107), so a user who writes `FerroField(unique=True, index=True)` likely gets *both* a unique constraint AND a redundant non-unique index emitted, with no warning. Two near-identical APIs now have opposite UX for the identical mistake. Whichever behavior is correct, the divergence itself is the maintainability cost: the next reader has to remember which constructor warns and which doesn't, and the rationale (`unique implies index`) applies equally to both.",
+      "suggestion": "Pick one rule and apply it to both constructors. Either (a) extract a shared `_normalize_unique_index(unique, index, owner) -> tuple[bool, bool]` helper that warns + drops in both classes, or (b) push the redundancy check entirely into the schema layer where both code paths converge, removing the logic from `__init__` for ForeignKey. Option (a) keeps validation close to the user; option (b) eliminates the silent-mutation problem from finding #1 simultaneously. Either way, do not ship the asymmetry.",
+      "user_flagged": true
+    },
+    {
+      "id": "fk-schema-property-contract-divergence",
+      "title": "Schema property keys for `index`/`unique` are written conditionally on the FK path and unconditionally on the FerroField path",
+      "file": "src/ferro/schema_metadata.py",
+      "lines": "106-107, 130-133",
+      "category": "coupling / contract-clarity",
+      "severity": "low",
+      "confidence": 45,
+      "description": "FerroField path: `prop[\"unique\"] = metadata.unique; prop[\"index\"] = metadata.index` (always present, bool). ForeignKey path: `if metadata.unique: prop[\"unique\"] = True; if metadata.index: prop[\"index\"] = True` (key absent when False). Downstream Rust DDL consumers and any other reader of this schema dict now have to handle two shapes for the same logical property -- 'False' vs 'absent'. This is the kind of subtle inconsistency that bites later when someone adds a third consumer and assumes the keys are always present.",
+      "suggestion": "Match the FerroField shape on the ForeignKey path: write `prop[\"index\"] = metadata.index` and `prop[\"unique\"] = metadata.unique` unconditionally. The Rust side already treats absence and `false` as equivalent in the new test, so this is a no-op behavior change today, but it locks in a single contract."
+    }
+  ],
+  "residual_risks": [
+    {
+      "id": "fk-index-naming-divergence",
+      "description": "Docs explicitly call out that Alembic autogen produces `ix_project_org_id` while the Rust runtime DDL produces `idx_project_org_id`. This is honest but it is a real foot-gun: a user comparing migration output against a database created via `auto_migrate=True` will see two indexes with different names for the same logical thing, or a 'phantom' index drop/create on the first autogen run after switching paths. Out of scope for this PR but worth tracking as a follow-up.",
+      "file": "docs/guide/relationships.md",
+      "confidence": 70
+    },
+    {
+      "id": "test-boilerplate-mild-duplication",
+      "description": "Four new tests in test_alembic_autogenerate.py each redeclare an `Org` model with `id` + `projects: Relation[list[\"Project\"]] = BackRef()` and a `Project` model that varies only in the ForeignKey kwargs. A pytest.parametrize over (fk_kwargs, expected_index, expected_unique) would shrink ~80 lines to ~30 and put the test cases in a single grid. Not blocking -- the duplication is local and readable -- but the next FK-feature test will copy this shape again and the cost compounds.",
+      "file": "tests/test_alembic_autogenerate.py",
+      "confidence": 40
+    }
+  ],
+  "testing_gaps": [
+    {
+      "id": "unique-implies-index-unverified-premise",
+      "description": "The redundancy warning's premise is 'unique=True already creates an implicit unique index'. The new tests verify that `unique=True, index=True` produces `index=False` on the SQLAlchemy column, but no test in this diff asserts that `ForeignKey(unique=True)` alone results in an actual unique index on the FK column at the DDL level (Alembic) or at the Rust runtime level. If that premise ever drifts -- e.g., a backend that enforces uniqueness via a constraint without a usable index -- the warning becomes misleading. Add a parity test analogous to `test_foreign_key_index_runtime_ddl_parity` for `unique=True` to lock in the assumption.",
+      "file": "tests/test_schema_constraints.py"
+    },
+    {
+      "id": "fk-index-postgres-runtime-parity-untested",
+      "description": "`test_foreign_key_index_runtime_ddl_parity` is `@pytest.mark.sqlite_only`. The Rust schema test in src/schema.rs covers Postgres at the SQL-string level, but there is no end-to-end test that the Postgres runtime path actually creates the index and that its name (`idx_project_org_id`) matches what the Postgres-specific code emits. Given the docs explicitly mention Postgres FKs as the motivating use case, a Postgres parity test is worth adding before relying on this in production."
+    }
+  ],
+  "summary": "Three low-severity maintainability findings, all on the same axis: the new `unique+index` redundancy logic was added asymmetrically. Concretely (1) it silently mutates `self.index` so the public attribute disagrees with the constructor argument, (2) it diverges from FerroField which has the same redundancy but no warning, and (3) it writes the schema property dict in a different shape than the FerroField path. The cleanest fix collapses all three: extract a shared normalize helper used by both constructors *or* push the redundancy decision into schema_metadata.py and stop mutating the metadata object. Tests are correct and well-placed but contain mild boilerplate duplication and leave the 'unique implies index' premise itself unverified."
+}

ferro_orm-0.5.0/.context/compound-engineering/ce-code-review/20260428-081705-bdeab5a2/project-standards.json

@@ -0,0 +1,45 @@
+{
+  "reviewer": "project-standards",
+  "scope": {
+    "branch": "feat/foreign-key-index-32",
+    "pr": 36,
+    "standards_file": ".cursorrules"
+  },
+  "audit_summary": {
+    "tdd_workflow": {
+      "compliant": true,
+      "evidence": "Commit 02d8184 'test: red test for ForeignKey(index=True) shadow column index' is the first commit on the branch and precedes all feat commits (9c3f9cf, b6a41b4, 8e4423c). Matches .cursorrules \u00a74 Step 1: 'Write the Integration Test First'."
+    },
+    "rust_unit_tests_present": {
+      "compliant": true,
+      "evidence": "src/schema.rs adds test_foreign_key_column_with_index_flag_emits_create_index covering both Sqlite and Postgres dialects, asserting CREATE INDEX, the idx_project_org_id name, and absence of CREATE UNIQUE INDEX. Satisfies .cursorrules \u00a75.1."
+    },
+    "python_integration_tests_present": {
+      "compliant": true,
+      "evidence": "tests/test_alembic_autogenerate.py adds 4 cases (index emission, unique+index warning, default false, nullable FK) and tests/test_schema_constraints.py adds test_foreign_key_index_runtime_ddl_parity exercising the compiled Rust runtime DDL. Satisfies .cursorrules \u00a75.2."
+    },
+    "no_unwrap_introduced": {
+      "compliant": true,
+      "evidence": "Diff contains zero occurrences of unwrap(). The new Rust test uses safe destructuring of build_create_table_sqls and Vec::join. Satisfies .cursorrules \u00a74 Step 3 'Never use unwrap()'."
+    },
+    "pyo3_bound_apis": {
+      "compliant": true,
+      "evidence": "PyO3 layer is not touched by this change (only src/schema.rs test module, plus pure-Python files). The Bound<'_, PyModule> requirement is out of scope."
+    },
+    "changelog_unreleased_entry": {
+      "compliant": true,
+      "evidence": "CHANGELOG.md adds a bullet under '## Unreleased' \u2192 '### Features' linking issue #32: 'Add `ForeignKey(index=True)` to emit a non-unique index on the shadow `*_id` column...'"
+    },
+    "bridge_thinness_parse_json_in_rust": {
+      "compliant": true,
+      "evidence": "src/ferro/schema_metadata.py only sets `prop[\"index\"] = True` on the JSON schema dict (lightweight serialization). All semantic interpretation (index DDL emission, naming) happens in Rust (src/schema.rs). Matches .cursorrules \u00a76 'FFI Efficiency: Pass JSON or primitives; parse in Rust.'"
+    },
+    "frequent_conventional_commits": {
+      "compliant": true,
+      "evidence": "8 commits on branch, all conventional with scope: 02d8184 test:, 9c3f9cf feat(fk):, b6a41b4 feat(fk):, 8e4423c feat(fk):, 260976c test(fk):, a0e84d6 test(fk):, b58c126 test(rust):, 3ccef38 docs(fk):. Each commit isolates a single concern (red test \u2192 minimal kwarg \u2192 propagation \u2192 warn \u2192 regression guards \u2192 runtime parity \u2192 rust unit \u2192 docs+changelog)."
+    }
+  },
+  "findings": [],
+  "residual_risks": [],
+  "testing_gaps": []
+}

ferro_orm-0.5.0/.context/compound-engineering/ce-code-review/20260428-081705-bdeab5a2/testing.json

@@ -0,0 +1,108 @@
+{
+  "reviewer": "testing",
+  "findings": [
+    {
+      "id": "testing-001-autogen-idempotency-gap",
+      "title": "No autogen-idempotency test for FK index; ix_* vs idx_* naming asymmetry will silently produce drift",
+      "severity": "P1",
+      "confidence": 75,
+      "autofix_class": "manual",
+      "owner": "review-fixer",
+      "files": [
+        "tests/test_alembic_autogenerate.py",
+        "tests/test_schema_constraints.py"
+      ],
+      "evidence": {
+        "diff_signal": "docs/guide/relationships.md (lines 357-360) explicitly documents the naming asymmetry: Alembic emits 'ix_project_org_id' (SQLAlchemy convention) while Rust runtime DDL emits 'idx_project_org_id'. The PR adds zero tests that run alembic.autogenerate.compare_metadata after auto_migrate to confirm this asymmetry does not produce phantom diffs.",
+        "precedent": "tests/test_composite_index.py::test_autogen_idempotent_after_first_apply (lines 690-724) establishes the team's pattern for catching exactly this class of bug for composite indexes. The new FK index feature has no equivalent guard.",
+        "regression_path": "After auto_migrate creates idx_project_org_id in the DB, compare_metadata(ctx, get_metadata()) sees: (a) an unexpected DB index 'idx_project_org_id' Alembic wants to drop, and (b) a missing index 'ix_project_org_id' Alembic wants to create. Every subsequent autogen run produces a non-empty diff. A naive `alembic revision --autogenerate` followed by `upgrade` will drop the Rust-created index and replace it with the Alembic-named one, silently mutating the deployed schema."
+      },
+      "recommended_fix": "Add an asyncio + sqlite_only test that calls connect(auto_migrate=True) for a model with ForeignKey(index=True), then runs compare_metadata on a sync engine and asserts the resulting diff contains no entries that match 'project' or 'org_id'. Mirror the structure of test_autogen_idempotent_after_first_apply. If the diff is non-empty (which it likely will be due to ix_/idx_ asymmetry), the implementation needs reconciliation (e.g., emit an Index() with name='idx_*' on the SA Column instead of relying on the bare index=True default convention).",
+      "rationale": "This is the question the user asked in the prompt verbatim: 'autogenerate diff-detection between two model versions'. Coverage gap is provable from the diff and from the docs that flag the asymmetry."
+    },
+    {
+      "id": "testing-002-no-postgres-end-to-end-runtime-ddl",
+      "title": "FK runtime-DDL parity test is SQLite-only; no Postgres analog queries pg_indexes",
+      "severity": "P2",
+      "confidence": 75,
+      "autofix_class": "manual",
+      "owner": "review-fixer",
+      "files": ["tests/test_schema_constraints.py"],
+      "evidence": {
+        "diff_signal": "tests/test_schema_constraints.py adds test_foreign_key_index_runtime_ddl_parity gated by @pytest.mark.sqlite_only. The Rust unit test in src/schema.rs iterates both SqlDialect::Sqlite and SqlDialect::Postgres but only asserts substring presence on the rendered SQL string -- it does not execute that SQL against a live Postgres engine.",
+        "precedent": "tests/test_schema_constraints.py::test_foreign_key_constraint_exists_in_postgres (lines 88-140) demonstrates the team's pattern for verifying FK behavior end-to-end on Postgres via information_schema queries. The new feature breaks this pattern.",
+        "regression_path": "Identifier quoting differences, search_path interactions, schema-qualified naming, or IF NOT EXISTS semantics on Postgres < 9.5 (sea_query emits the keyword unconditionally per src/schema.rs:342) could fail at runtime. The Rust string-level unit test will not catch a real connection failure or a partial-DDL situation where the table is created but the index step rolls back."
+      },
+      "recommended_fix": "Add @pytest.mark.postgres_only async test that runs auto_migrate with ForeignKey(index=True), then queries SELECT indexname FROM pg_indexes WHERE schemaname=%s AND tablename='project' and asserts 'idx_project_org_id' is present and is non-unique (verify via pg_index.indisunique = false). Reuse the postgres_base_url / db_schema_name fixtures already used by test_foreign_key_constraint_exists_in_postgres."
+    },
+    {
+      "id": "testing-003-nullable-fk-index-not-verified-at-ddl-level",
+      "title": "Nullable FK + index combination only verified at SA-metadata level, not at runtime DDL",
+      "severity": "P2",
+      "confidence": 50,
+      "autofix_class": "manual",
+      "owner": "review-fixer",
+      "files": ["tests/test_alembic_autogenerate.py"],
+      "evidence": {
+        "diff_signal": "test_foreign_key_index_with_nullable_fk only checks project_table.c.org_id.index is True / nullable is True (SA metadata flags). The runtime-DDL parity test uses the default non-null CASCADE case. The Rust unit test in schema.rs uses ferro_nullable: false.",
+        "regression_path": "A future change that conditionally suppresses the CREATE INDEX emission for nullable FK columns (e.g., to switch to a partial index 'WHERE org_id IS NOT NULL' for storage savings) would pass test_foreign_key_index_with_nullable_fk and the Rust unit test, but would silently regress the documented contract that the index is created for nullable FKs."
+      },
+      "recommended_fix": "Either (a) add ferro_nullable: true variant to the existing Rust unit test in src/schema.rs, OR (b) add 'org: Org | None' with on_delete='SET NULL' + index=True to test_foreign_key_index_runtime_ddl_parity and assert idx_project_org_id is still emitted in sqlite_master."
+    },
+    {
+      "id": "testing-004-warning-negative-path-uncovered",
+      "title": "No assertion that UserWarning is silent for index=True alone or unique=True alone",
+      "severity": "P3",
+      "confidence": 50,
+      "autofix_class": "safe_auto",
+      "owner": "review-fixer",
+      "files": ["tests/test_alembic_autogenerate.py"],
+      "evidence": {
+        "diff_signal": "test_foreign_key_unique_implies_index_warns asserts the warning fires for unique=True+index=True. test_foreign_key_index_emits_single_column_index uses index=True alone but does not wrap the class definition in pytest.warns / pytest.warns(None) / a recwarn fixture to confirm no UserWarning is emitted. Same for test_foreign_key_index_default_false.",
+        "regression_path": "A future change that broadens the redundancy condition (e.g., warning whenever index=True regardless of unique) would not fail any current test. The warning-on path is tested; the warning-off path is implied but unverified."
+      },
+      "recommended_fix": "Wrap one of the existing index=True tests in 'with warnings.catch_warnings(record=True) as ws: warnings.simplefilter(\"always\")' and assert no UserWarning matching 'redundant' was captured. Cheap to add."
+    },
+    {
+      "id": "testing-005-default-false-omits-json-key-not-verified",
+      "title": "test_foreign_key_index_default_false asserts SA metadata only; doesn't verify schema-JSON behavior is bit-for-bit identical to pre-PR",
+      "severity": "P3",
+      "confidence": 50,
+      "autofix_class": "advisory",
+      "owner": "review-fixer",
+      "files": ["tests/test_alembic_autogenerate.py", "src/ferro/schema_metadata.py"],
+      "evidence": {
+        "diff_signal": "src/ferro/schema_metadata.py:132-133 uses 'if metadata.index: prop[\"index\"] = True' for FK columns (conditional set), unlike line 107 for ferro_fields which unconditionally sets prop['index'] = metadata.index. The new test asserts SA Column.index is False but does not assert the underlying JSON schema property for org_id either lacks the 'index' key entirely or has it set to False.",
+        "intent_in_pr_description": "The PR explicitly states 'Existing index=False behavior must remain bit-for-bit identical.' The current test verifies the SA-level outcome, which is downstream of both the JSON shape AND the alembic.py renderer's get('index', False) fallback. A regression that flipped the schema_metadata.py line to 'prop[\"index\"] = metadata.index' (unconditional) would change the JSON shape (key now present with value False) without changing observable SA metadata, slipping past tests but potentially affecting CDC consumers or external schema-JSON consumers."
+      },
+      "recommended_fix": "Add a one-liner assertion in test_foreign_key_index_default_false that calls build_model_schema(Project) and asserts 'index' not in schema['properties']['org_id']. Or relax the requirement and document that 'bit-for-bit identical' applies to SA metadata only."
+    }
+  ],
+  "residual_risks": [
+    "Alembic autogen drift between Rust-emitted 'idx_*' indexes and SQLAlchemy-default 'ix_*' indexes is the highest-risk silent failure mode for this feature. Any team running 'alembic revision --autogenerate' after an auto_migrate may unwittingly produce a migration that drops the Rust index and recreates it under a different name -- and no test in this PR will surface that.",
+    "Postgres-specific behaviors (search_path, schema qualification under multi-tenant schemas, IF NOT EXISTS on legacy Postgres) are not exercised end-to-end. The project has multi-tenant schema fixtures (db_schema_name) used elsewhere; the new feature does not opt in.",
+    "The pytest.warns(UserWarning, match='redundant') assertion is intentionally loose on wording (good for refactor resilience) but will not detect a future change that emits the warning at the wrong stacklevel, causing it to surface as if from the ForeignKey internal frame rather than the user's class definition."
+  ],
+  "testing_gaps": [
+    {
+      "area": "composite_indexes + FK shadow column interaction",
+      "description": "A model declaring both __ferro_composite_indexes__ = ((\"org_id\", \"name\"),) and ForeignKey(index=True) on the relation would request two distinct indexes on overlapping columns (a single-column ix on org_id and a composite on org_id+name). No test exercises this; the warn_and_drop_overlap_with_uniques() helper handles only composite-vs-unique overlaps, not single-column FK-index vs composite. Likely fine (additive) but unverified.",
+      "confidence": 50
+    },
+    {
+      "area": "unique=True alone without index=True",
+      "description": "Pre-existing behavior; this PR doesn't regress it. But the new assertions on profile_table.c.user_id.unique is True / index is False rely on the implementation in schema_metadata.py:130-133 being bypassed correctly for the unique-only case. No targeted test for a model with unique=True alone in the new test additions; the assertion piggybacks on the redundancy-warning test only.",
+      "confidence": 50
+    },
+    {
+      "area": "Warning stacklevel and emission location",
+      "description": "src/ferro/base.py:158 sets stacklevel=2. No test asserts the warning surfaces from the user's class-definition frame. A refactor that wraps __init__ in another helper would silently break the user-facing warning location.",
+      "confidence": 25
+    },
+    {
+      "area": "Idempotency of repeated auto_migrate calls",
+      "description": "Rust DDL uses .if_not_exists() (src/schema.rs:342) on the index creation, but no test calls connect(auto_migrate=True) twice and asserts the second call succeeds without error. The composite_indexes test suite has equivalent coverage; FK index does not.",
+      "confidence": 50
+    }
+  ]
+}

{ferro_orm-0.3.4 → ferro_orm-0.5.0}/.github/workflows/ci.yml

@@ -70,15 +70,26 @@ jobs:
       - name: Set up Rust
         uses: dtolnay/rust-toolchain@stable
 
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
       - name: Cache Rust build
         uses: Swatinem/rust-cache@v2
         with:
-          prefix-key: v1
+          prefix-key: v2
           cache-on-failure: true
 
       - name: Run Rust tests
+        env:
+          PYO3_PYTHON: ${{ env.pythonLocation }}/bin/python
         run: |
-          cargo test --all-features
+          # extension-module skips libpython linking; disable it for tests so the
+          # cargo test binary can resolve Python symbols against the installed runtime.
+          # The `testing` feature pulls in pyo3/auto-initialize so unit tests that
+          # call Python::attach start the interpreter automatically.
+          cargo test --no-default-features --features testing
 
   test-python-pr:
     name: Python tests (PR / 3.13)