codepulse-engine 0.1.0__py3-none-any.whl

codepulse/storage/schema_migrations/versions/21a7cb7f1a85_initial_schema.py

@@ -0,0 +1,105 @@
+"""initial_schema
+
+Revision ID: 21a7cb7f1a85
+Revises: 
+Create Date: 2026-09-01 23:26:31.067744
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '21a7cb7f1a85'
+down_revision: Union[str, Sequence[str], None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 1. Repositories
+    op.create_table(
+        'repositories',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('team_id', sa.Integer(), nullable=False, server_default='1'),
+        sa.Column('name', sa.String(length=255), nullable=False),
+        sa.Column('url', sa.Text(), nullable=False),
+        sa.Column('branch', sa.String(length=100), nullable=True, server_default='main'),
+        sa.Column('last_sync', sa.DateTime(), nullable=True),
+        sa.Column('file_count', sa.Integer(), nullable=True, server_default='0'),
+        sa.Column('symbol_count', sa.Integer(), nullable=True, server_default='0'),
+        sa.PrimaryKeyConstraint('id'),
+    )
+
+    # 2. Files
+    op.create_table(
+        'files',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('repo_id', sa.Integer(), nullable=False),
+        sa.Column('path', sa.Text(), nullable=False),
+        sa.Column('language', sa.String(length=50), nullable=False),
+        sa.Column('size_bytes', sa.Integer(), nullable=True, server_default='0'),
+        sa.Column('line_count', sa.Integer(), nullable=True, server_default='0'),
+        sa.Column('last_indexed', sa.DateTime(), nullable=True),
+        sa.ForeignKeyConstraint(['repo_id'], ['repositories.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id'),
+    )
+
+    # 3. Symbols
+    op.create_table(
+        'symbols',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('file_id', sa.Integer(), nullable=False),
+        sa.Column('name', sa.String(length=255), nullable=False),
+        sa.Column('type', sa.String(length=50), nullable=False),
+        sa.Column('start_line', sa.Integer(), nullable=False),
+        sa.Column('end_line', sa.Integer(), nullable=False),
+        sa.Column('signature', sa.Text(), nullable=True, server_default=''),
+        sa.Column('docstring', sa.Text(), nullable=True),
+        sa.Column('body', sa.Text(), nullable=True, server_default=''),
+        sa.Column('body_hash', sa.String(length=64), nullable=True, server_default=''),
+        sa.Column('language', sa.String(length=50), nullable=False),
+        sa.Column('complexity', sa.Integer(), nullable=True, server_default='1'),
+        sa.ForeignKeyConstraint(['file_id'], ['files.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    op.create_index('ix_symbols_name', 'symbols', ['name'], unique=False)
+
+    # 4. Dependencies
+    op.create_table(
+        'dependencies',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('source_symbol_name', sa.String(length=255), nullable=False),
+        sa.Column('source_file', sa.Text(), nullable=False),
+        sa.Column('target_symbol_name', sa.String(length=255), nullable=False),
+        sa.Column('target_file', sa.Text(), nullable=True),
+        sa.Column('call_count', sa.Integer(), nullable=True, server_default='1'),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    op.create_index('ix_dependencies_source_symbol_name', 'dependencies', ['source_symbol_name'], unique=False)
+    op.create_index('ix_dependencies_target_symbol_name', 'dependencies', ['target_symbol_name'], unique=False)
+
+    # 5. Code Embeddings
+    op.create_table(
+        'code_embeddings',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('symbol_id', sa.Integer(), nullable=False),
+        sa.Column('chunk_type', sa.String(length=50), nullable=True, server_default='signature_doc'),
+        sa.Column('embedding_json', sa.Text(), nullable=False),
+        sa.Column('chunk_content', sa.Text(), nullable=True, server_default=''),
+        sa.ForeignKeyConstraint(['symbol_id'], ['symbols.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id'),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table('code_embeddings')
+    op.drop_index('ix_dependencies_target_symbol_name', table_name='dependencies')
+    op.drop_index('ix_dependencies_source_symbol_name', table_name='dependencies')
+    op.drop_table('dependencies')
+    op.drop_index('ix_symbols_name', table_name='symbols')
+    op.drop_table('symbols')
+    op.drop_table('files')
+    op.drop_table('repositories')

codepulse/storage/schema_migrations/versions/2cd38eb12a7e_add_call_edge_repo_id_isolation_fix.py

@@ -0,0 +1,112 @@
+"""add_call_edge_repo_id_isolation_fix
+
+Revision ID: 2cd38eb12a7e
+Revises: f6e481353553
+Create Date: 2026-09-16 00:00:00.000000
+
+Repository-isolation fix (not a named roadmap sprint item -- a real,
+confirmed correctness/security bug found and disclosed by a Phase 3.4
+pre-commit audit, fixed on the user's explicit instruction before
+starting Phase 3.5).
+
+`call_edges` (né `dependencies`/`DependencyModel`) has never carried a
+repository association, since its Phase 0.4 introduction. `GET
+/v1/symbols/{id}` queries it by symbol name alone -- confirmed LIVE, in
+this session, that a caller authorized for one repository can receive
+another, unrelated repository's call-graph edges (symbol name + file
+path) whenever symbol names happen to collide across repositories. This
+directly violates the roadmap's "Repository isolation" permanent
+invariant (CLAUDE.md §4) and §15/§30's "every query... filtered by
+repository_id" rule.
+
+This migration:
+
+  1. Adds a new, nullable `repo_id` column (FK to `repositories.id`,
+     `ondelete='CASCADE'`, indexed -- the exact same pattern every other
+     `repo_id` column in this schema already uses), via batch mode
+     (SQLite requires a table rebuild to add a real FK constraint after
+     the fact, the same reason `20fc2d0607e2` used batch mode to add a
+     constraint to an existing table).
+  2. Backfills existing rows conservatively and HONESTLY -- never a
+     guess (CLAUDE.md: no fabricated metrics). For each distinct
+     `source_file` value already present in `call_edges`, this looks up
+     every `files.path` row that matches it: if exactly ONE distinct
+     `repo_id` results (the common case -- most databases have only one,
+     or a small number of, repositories, and most file paths are not
+     duplicated verbatim across them), every matching row is backfilled
+     with that `repo_id`. If the match is AMBIGUOUS (two or more
+     repositories happen to have a file at that exact same relative
+     path) or there is NO match at all (the file was since renamed,
+     moved, or deleted), the row is left with `repo_id = NULL` rather
+     than guessing -- a `NULL`-`repo_id` row is simply invisible to every
+     repository-scoped query from now on (a real, disclosed, one-time
+     completeness gap for that specific historical edge, not a security
+     problem -- the opposite of the bug being fixed), until its
+     repository is next re-indexed and persists a fresh, correctly
+     `repo_id`-tagged replacement edge.
+
+Non-destructive: no existing row is deleted, and no existing column's
+value is changed. `IndexingEngine._persist_to_db` now sets `repo_id` on
+every NEW `CallEdge` row going forward (see that method's own comment) --
+this migration only concerns rows that already existed before this fix.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '2cd38eb12a7e'
+down_revision: Union[str, Sequence[str], None] = 'f6e481353553'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    with op.batch_alter_table('call_edges', schema=None) as batch_op:
+        batch_op.add_column(sa.Column('repo_id', sa.Integer(), nullable=True))
+        batch_op.create_foreign_key(
+            'fk_call_edges_repo_id_repositories', 'repositories', ['repo_id'], ['id'], ondelete='CASCADE'
+        )
+    op.create_index(op.f('ix_call_edges_repo_id'), 'call_edges', ['repo_id'], unique=False)
+
+    _backfill_repo_id()
+
+
+def _backfill_repo_id() -> None:
+    """
+    Conservative, honest backfill -- see this module's own docstring for
+    the exact rule. Only ever sets `repo_id` when exactly one repository
+    can be identified for a given `source_file` value; leaves it `NULL`
+    otherwise (ambiguous match, or no match at all).
+    """
+    bind = op.get_bind()
+
+    distinct_files = bind.execute(sa.text("SELECT DISTINCT source_file FROM call_edges")).fetchall()
+    for (source_file,) in distinct_files:
+        matching_repo_ids = bind.execute(
+            sa.text("SELECT DISTINCT repo_id FROM files WHERE path = :p"),
+            {"p": source_file},
+        ).fetchall()
+        if len(matching_repo_ids) == 1:
+            bind.execute(
+                sa.text(
+                    "UPDATE call_edges SET repo_id = :r "
+                    "WHERE source_file = :p AND repo_id IS NULL"
+                ),
+                {"r": matching_repo_ids[0][0], "p": source_file},
+            )
+        # else: 0 matches (file since renamed/moved/deleted) or 2+
+        # distinct repo_id matches (the same relative path exists in
+        # more than one repository -- genuinely ambiguous) -- leave
+        # NULL, honestly, rather than guessing.
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_index(op.f('ix_call_edges_repo_id'), table_name='call_edges')
+    with op.batch_alter_table('call_edges', schema=None) as batch_op:
+        batch_op.drop_constraint('fk_call_edges_repo_id_repositories', type_='foreignkey')
+        batch_op.drop_column('repo_id')

codepulse/storage/schema_migrations/versions/3ba396e9c78f_add_symbol_natural_key_uniqueness.py

@@ -0,0 +1,80 @@
+"""add_symbol_natural_key_uniqueness
+
+Revision ID: 3ba396e9c78f
+Revises: 20fc2d0607e2
+Create Date: 2026-09-05 13:29:49.980342
+
+Phase 0.4 (Symbol upsert by (file_id, name, start_line)).
+
+This migration is additive and non-destructive:
+
+  - Adds a UNIQUE constraint on `symbols(file_id, name, start_line)`,
+    enforcing the natural-key invariant the Phase 0.4 upsert logic depends
+    on (roadmap §8: "Symbol rows, upserted by (file_id, name, start_line)
+    key"). A pre-flight check aborts the migration (rather than failing
+    partway through a batch table-recreate, or silently accepting an
+    inconsistent state) if any pre-existing duplicate rows would violate
+    this constraint.
+
+  - No column is added and no data is transformed -- `symbols.body_hash`
+    already existed from the initial schema and is reused as-is for
+    Phase 0.4's change-detection logic (no new hashing convention is
+    introduced by this migration).
+
+No table is dropped or recreated destructively and no existing row is
+deleted, inserted, or overwritten. SQLAlchemy/Alembic "batch" mode is used
+because SQLite requires a copy-and-swap under the hood to add a constraint
+to an existing table -- all existing rows and columns are carried over
+unchanged by that process.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '3ba396e9c78f'
+down_revision: Union[str, Sequence[str], None] = '20fc2d0607e2'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _assert_no_duplicates() -> None:
+    """
+    Pre-flight safety check: refuse to add the UNIQUE constraint if any
+    pre-existing data would violate it, rather than letting the batch
+    table-recreate fail halfway (or, on backends that don't error the same
+    way, silently accepting an inconsistent state).
+    """
+    bind = op.get_bind()
+
+    dup_symbols = bind.execute(
+        sa.text(
+            "SELECT file_id, name, start_line, COUNT(*) AS c FROM symbols "
+            "GROUP BY file_id, name, start_line HAVING COUNT(*) > 1"
+        )
+    ).fetchall()
+    if dup_symbols:
+        raise RuntimeError(
+            "Cannot add UNIQUE constraint on symbols(file_id, name, "
+            "start_line): duplicate rows already exist: "
+            f"{[(row[0], row[1], row[2]) for row in dup_symbols]}. Resolve "
+            "duplicate Symbol rows before applying this migration."
+        )
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    _assert_no_duplicates()
+
+    with op.batch_alter_table("symbols", schema=None) as batch_op:
+        batch_op.create_unique_constraint(
+            "uq_symbols_file_id_name_start_line", ["file_id", "name", "start_line"]
+        )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    with op.batch_alter_table("symbols", schema=None) as batch_op:
+        batch_op.drop_constraint("uq_symbols_file_id_name_start_line", type_="unique")

codepulse/storage/schema_migrations/versions/49572f834366_add_embedding_persistence_fields.py

@@ -0,0 +1,102 @@
+"""add_embedding_persistence_fields
+
+Revision ID: 49572f834366
+Revises: 3ba396e9c78f
+Create Date: 2026-09-05 14:19:04.742535
+
+Phase 0.5 (Embedding persistence + hydration).
+
+This migration is additive and non-destructive:
+
+  - Adds `code_embeddings.chunk_index` (NOT NULL, default 0), completing the
+    natural key `(symbol_id, chunk_type, chunk_index)` specified by the
+    roadmap's Phase 0 idempotency rule (§8). Every pre-existing row
+    implicitly becomes chunk_index=0 (there was no concept of multiple
+    indexed chunks per (symbol, chunk_type) before this migration).
+  - Adds `code_embeddings.content_hash` (nullable) for change detection --
+    left NULL for pre-existing rows, for the same reason `files.content_hash`
+    was left NULL in the Phase 0.3 migration: the exact chunk text that
+    produced a historical row was never separately hashed, so no
+    historically-accurate hash can be reconstructed without fabricating one.
+    Each such row gets a real hash the next time its symbol is re-indexed.
+  - Adds `code_embeddings.embedding_model` and `code_embeddings.embedding_dim`
+    (both nullable), recording which model/dimension produced a vector so
+    hydration can detect a model or dimension change and skip loading an
+    incompatible vector rather than silently corrupting the in-memory
+    vector index.
+  - Adds a UNIQUE constraint on `code_embeddings(symbol_id, chunk_type,
+    chunk_index)`. A pre-flight check aborts the migration (rather than
+    failing partway through a batch table-recreate, or silently accepting
+    an inconsistent state) if any pre-existing (symbol_id, chunk_type) pair
+    already has more than one row -- such rows would collide once they all
+    default to chunk_index=0.
+
+No table is dropped or recreated destructively and no existing row is
+deleted or has its embedding_json/chunk_content overwritten. SQLAlchemy/
+Alembic "batch" mode is used because SQLite requires a copy-and-swap under
+the hood to add columns and a constraint to an existing table -- all
+existing rows are carried over unchanged by that process.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '49572f834366'
+down_revision: Union[str, Sequence[str], None] = '3ba396e9c78f'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _assert_no_duplicates() -> None:
+    """
+    Pre-flight safety check: refuse to add the UNIQUE constraint if any
+    pre-existing data would violate it once every row defaults to
+    chunk_index=0, rather than letting the batch table-recreate fail
+    halfway (or, on backends that don't error the same way, silently
+    accepting an inconsistent state).
+    """
+    bind = op.get_bind()
+
+    dup = bind.execute(
+        sa.text(
+            "SELECT symbol_id, chunk_type, COUNT(*) AS c FROM code_embeddings "
+            "GROUP BY symbol_id, chunk_type HAVING COUNT(*) > 1"
+        )
+    ).fetchall()
+    if dup:
+        raise RuntimeError(
+            "Cannot add UNIQUE constraint on code_embeddings(symbol_id, "
+            "chunk_type, chunk_index): duplicate (symbol_id, chunk_type) "
+            "pairs already exist, and would collide once defaulted to "
+            f"chunk_index=0: {[(row[0], row[1]) for row in dup]}. Resolve "
+            "duplicate embedding rows before applying this migration."
+        )
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    _assert_no_duplicates()
+
+    with op.batch_alter_table("code_embeddings", schema=None) as batch_op:
+        batch_op.add_column(
+            sa.Column("chunk_index", sa.Integer(), nullable=False, server_default="0")
+        )
+        batch_op.add_column(sa.Column("content_hash", sa.String(length=64), nullable=True))
+        batch_op.add_column(sa.Column("embedding_model", sa.String(length=150), nullable=True))
+        batch_op.add_column(sa.Column("embedding_dim", sa.Integer(), nullable=True))
+        batch_op.create_unique_constraint(
+            "uq_code_embeddings_symbol_chunk", ["symbol_id", "chunk_type", "chunk_index"]
+        )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    with op.batch_alter_table("code_embeddings", schema=None) as batch_op:
+        batch_op.drop_constraint("uq_code_embeddings_symbol_chunk", type_="unique")
+        batch_op.drop_column("embedding_dim")
+        batch_op.drop_column("embedding_model")
+        batch_op.drop_column("content_hash")
+        batch_op.drop_column("chunk_index")

codepulse/storage/schema_migrations/versions/7c3e5a91d2f4_add_module_edges.py

@@ -0,0 +1,61 @@
+"""add_module_edges
+
+Revision ID: 7c3e5a91d2f4
+Revises: b9014c049e33
+Create Date: 2026-10-12 00:00:00.000000
+
+Persists the file-level import graph so module structure survives a
+restart (CODEPULSE_FUTURE_CHANGES.md item 15; user-approved change to
+Phase 4.3's original "no persistence" scope).
+
+`GET /v1/repositories/{id}/modules`, the CLI `modules` command, the MCP
+`module_structure` tool and the VS Code Module Structure view all read
+`IndexingEngine.analyze_module_structure`, which built its graph from
+`parse_results`, an in-memory cache. After any server restart module
+structure was therefore empty (0 clusters) until the repository was
+re-indexed, because imports were not stored anywhere. The call graph
+(`call_edges`) and the symbol map (`symbols`/`files`) could be restored from
+existing tables; this one could not.
+
+This migration is purely additive and non-destructive: it only CREATES
+`module_edges` (one row per resolved source-file -> target-file import edge,
+plus one row with a NULL `target_file` for each file that has no resolved
+imports, so the node set is stored too; `repo_id` NOT NULL with ON DELETE
+CASCADE, unique per (repo_id, source_file, target_file)). No existing table,
+column or row is touched, so there is no pre-existing-data failure mode and
+no backfill: a repository's rows are written the next time it is indexed
+(until then its module structure behaves exactly as it did before this
+migration -- cold after a restart, never a misleading partial graph).
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '7c3e5a91d2f4'
+down_revision: Union[str, Sequence[str], None] = 'b9014c049e33'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.create_table(
+        'module_edges',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('repo_id', sa.Integer(), nullable=False),
+        sa.Column('source_file', sa.Text(), nullable=False),
+        sa.Column('target_file', sa.Text(), nullable=True),
+        sa.ForeignKeyConstraint(['repo_id'], ['repositories.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('repo_id', 'source_file', 'target_file', name='uq_module_edges_repo_source_target'),
+    )
+    op.create_index(op.f('ix_module_edges_repo_id'), 'module_edges', ['repo_id'], unique=False)
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_index(op.f('ix_module_edges_repo_id'), table_name='module_edges')
+    op.drop_table('module_edges')

codepulse/storage/schema_migrations/versions/a41f0d2c6b8e_canonicalize_repository_urls.py

@@ -0,0 +1,94 @@
+"""canonicalize_repository_urls
+
+Revision ID: a41f0d2c6b8e
+Revises: 7c3e5a91d2f4
+Create Date: 2026-10-14 00:00:00.000000
+
+Repository identity (CODEPULSE_FUTURE_CHANGES.md item 2; user-approved).
+
+A repository was identified by the exact string it was first indexed under, so
+the same directory spelled with backslashes vs forward slashes, a trailing
+separator, `..` segments or a lowercase vs uppercase Windows drive letter became
+two repositories. From this revision on the application stores and compares ONE
+canonical form (see `codepulse.repository_identity`); this migration brings the
+rows that already exist into that form.
+
+DATA-ONLY and non-destructive: no table, column or constraint changes, nothing is
+deleted and nothing is merged.
+  - A row whose `url` is a LOCAL PATH is rewritten to its canonical form
+    (absolute, `..` resolved, symlinks resolved where the path exists, uppercase
+    drive letter on Windows, no trailing separator).
+  - Anything that is not a local path (`https://...`, `ssh://...`, `file:///...`)
+    is left exactly as it is.
+  - If another row already holds the canonical form -- a DUPLICATE that predates
+    this fix -- the row is left unchanged and the pair is logged as a warning.
+    The two rows each own their own files, symbols, embeddings, jobs and API-key
+    grants, so merging them is a decision for a person, not a migration. The
+    application still finds the lowest-id row for either spelling.
+
+The canonicalization is written out here (not imported) so this migration keeps
+doing what it did on the day it was written even if the application's rule later
+changes. If this runs on a machine where the paths do not exist (a restored
+backup), `realpath` cannot resolve symlinks or fix the case of components, so the
+result is the normalized absolute path with an uppercase drive letter; rows are
+only ever rewritten to a form no other row holds.
+
+Downgrade is a no-op: the original spellings were not recorded and cannot be
+restored, and the canonical form is valid under the previous schema too.
+"""
+import logging
+import os
+import re
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'a41f0d2c6b8e'
+down_revision: Union[str, Sequence[str], None] = '7c3e5a91d2f4'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+logger = logging.getLogger("alembic.runtime.migration")
+
+_URL_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.\-]*://")
+
+
+def _canonical(url: str) -> str:
+    if not url or _URL_SCHEME.match(url):
+        return url
+    resolved = os.path.realpath(os.path.abspath(url))
+    if os.name == "nt" and len(resolved) >= 2 and resolved[1] == ":":
+        resolved = resolved[0].upper() + resolved[1:]
+    return resolved
+
+
+def upgrade() -> None:
+    """Upgrade data."""
+    bind = op.get_bind()
+    rows = bind.execute(sa.text("SELECT id, url FROM repositories ORDER BY id")).fetchall()
+    taken = {url: repo_id for repo_id, url in rows}
+    rewritten = 0
+    for repo_id, url in rows:
+        canonical = _canonical(url)
+        if canonical == url:
+            continue
+        holder = taken.get(canonical)
+        if holder is not None and holder != repo_id:
+            logger.warning(
+                "repository %s (%r) and repository %s both name %r; left unchanged, merge them by hand if they are the same project",
+                repo_id, url, holder, canonical,
+            )
+            continue
+        bind.execute(sa.text("UPDATE repositories SET url = :u WHERE id = :i"), {"u": canonical, "i": repo_id})
+        del taken[url]
+        taken[canonical] = repo_id
+        rewritten += 1
+    if rewritten:
+        logger.info("canonicalized %d repository url(s)", rewritten)
+
+
+def downgrade() -> None:
+    """Downgrade: nothing to undo (the original spellings were not recorded)."""

codepulse/storage/schema_migrations/versions/b0bdd63949f4_add_api_key_model.py

@@ -0,0 +1,71 @@
+"""add_api_key_model
+
+Revision ID: b0bdd63949f4
+Revises: 49572f834366
+Create Date: 2026-09-08 20:50:33.127639
+
+Phase 1.1 (roadmap §37 item 1.1: "APIKey model + hashing + creation flow").
+
+This migration is purely additive and non-destructive: it creates two new
+tables (`api_keys`, `api_key_repositories`) and touches no existing table,
+column, or row. No `codepulse.db` data is read, transformed, or migrated.
+
+  - `api_keys`: one row per API key. Only `key_hash` (a SHA-256 hex digest)
+    is stored, never the raw key -- see codepulse.auth.hash_api_key.
+    `key_prefix` is a short, non-secret display value. `revoked_at` is
+    schema support for a future revocation flow (not implemented in Phase
+    1.1); it stays NULL for every key this milestone creates.
+  - `api_key_repositories`: a (api_key_id, repository_id) grant table
+    implementing "API keys ... scoped to one or more repositories"
+    (roadmap §15). Phase 1.1 only writes to this table (via
+    codepulse.auth.create_api_key) -- nothing reads/enforces it yet; that
+    is Phase 1.2's central authorization dependency.
+
+Since both tables are brand new, no pre-flight duplicate check is needed
+(unlike prior phases' migrations, which added constraints to existing,
+possibly-already-populated tables) -- there is no pre-existing data that
+could violate either table's UNIQUE constraint.
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'b0bdd63949f4'
+down_revision: Union[str, Sequence[str], None] = '49572f834366'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.create_table(
+        'api_keys',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('name', sa.String(length=255), nullable=False),
+        sa.Column('key_hash', sa.String(length=64), nullable=False),
+        sa.Column('key_prefix', sa.String(length=32), nullable=False),
+        sa.Column('created_at', sa.DateTime(), nullable=False),
+        sa.Column('revoked_at', sa.DateTime(), nullable=True),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('key_hash', name='uq_api_keys_key_hash'),
+    )
+
+    op.create_table(
+        'api_key_repositories',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('api_key_id', sa.Integer(), nullable=False),
+        sa.Column('repo_id', sa.Integer(), nullable=False),
+        sa.ForeignKeyConstraint(['api_key_id'], ['api_keys.id'], ondelete='CASCADE'),
+        sa.ForeignKeyConstraint(['repo_id'], ['repositories.id'], ondelete='CASCADE'),
+        sa.PrimaryKeyConstraint('id'),
+        sa.UniqueConstraint('api_key_id', 'repo_id', name='uq_api_key_repositories_key_repo'),
+    )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_table('api_key_repositories')
+    op.drop_table('api_keys')