intent-record 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2abf7a93c2bbefd6b31f0ff8ee7f08def82e721b1166885b8701f1f003162e7
-  data.tar.gz: f5754926ff4e9b0ff7d339423196487610e816bdd164f3fc96344fb9423ef83c
+  metadata.gz: '09016b9ff684f0f9137aa00a6848f68b6018cd870495a73d9ebfe11dd4706d8f'
+  data.tar.gz: 93d53144d6ea2bfe0c997d6242ed4e0e34843392998562824196d44494a0c569
 SHA512:
-  metadata.gz: 844a434054ae004e8bc75bb84b20e6d9a301842e860f66f715add6ac14926fa9c378d83a79d8fccabcdc97e9ff28a4b0c8fbed28194fc90b3f558ff687d6c5f5
-  data.tar.gz: 38a447b34c8fb3a2f4543c2d1c1e8d5cbb4d71669804cdd499b88ec6dfd1e48439fc26670f9e4e5bba838fa8bc4857a535a0abe6d9a8f59a2ed6008478904708
+  metadata.gz: 34aa8df17cbecd1c6eda808dde6dbb54d8c13d6acd5741c62b89cfdfb54843a942f951cd06e7f84935d45486609a90ec3d3696bcd30dfbf9230694d0c2bc9f41
+  data.tar.gz: bfccfc5091b3fde1060e638d6e9f3f451daad4d8a984ca144d705bae19133a948f10f555213061510eea2dda252312bc0dd07db87c14dcce5eba39087cdababf

data/CHANGELOG.md

@@ -6,6 +6,20 @@ Notable changes, one section per released version. The format follows
 
 ## Unreleased
 
+## 1.2.0 - 2026-09-20
+
+### Added
+
+- `blame`, which answers "why is this line here" for a range of lines. Blame output goes in on stdin, so the tool still never shells out to git and the same command works for Perforce or Mercurial. `--format git-porcelain` reads what `git blame --porcelain` prints, so the common case is one command.
+- Neighbouring lines from one change are answered once, as a span. A change the store has never heard of still gets a span, with no intents, and a line you have edited but not committed is marked `uncommitted`.
+- A search term can name one field: `summary:retry`, `body:retry`, `uri:ACME-42`, `title:flaky`. The name is read in any case. Only those four names count, so a ticket url is still searched as itself.
+
+### Changed
+
+- Search answers most relevant first rather than newest first, with a term in a summary counting for more than the same term in a long body. Each result carries the fragment of the body its terms landed in, and the GUI's search page shows that instead of every body in full.
+- A plain search word now also matches the other forms of itself, so `retry` finds a record that said `retried`. A term carrying punctuation is still matched as the literal you typed, so `100%` does not match "100 percent" and `ACME-4` still finds `ACME-42`.
+- Upgrading indexes the records a store already holds, so ranking works on existing history from the first run rather than only on what is recorded afterwards.
+
 ## 1.1.0 - 2026-09-19
 
 ### Added

data/README.md

@@ -7,6 +7,7 @@ Local records storage for the intent behind individual code changes.
 
 A commit message says what changed. The intent record says why: what the agent (or person) was trying to achieve, which ticket or design page asked for it, and which earlier change it builds on. intent-record stores that in a local SQLite database, links it to the commit hash, and answers the questions people and agents ask later.
 
+- "Why is this line here?" (`git blame --porcelain f.rb | intent-record blame --format git-porcelain`)
 - "What was this commit for?" (`lookup <hash>`)
 - "What did we build for this Jira ticket, and why that way?" (`by-source <url-or-key>`)
 - "Have we touched retry logic before, and what were we thinking?" (`search retry`)
@@ -46,6 +47,9 @@ intent-record lookup 8f3a1c2
 # Or comes at it from the ticket
 intent-record by-source ACME-42 --contains
 
+# Or is staring at one line of a file and wants to know why it is there
+git blame --porcelain lib/fetch.rb | intent-record blame --format git-porcelain
+
 # Or wants to read it in a browser
 intent-record serve
 ```
@@ -60,10 +64,11 @@ JSON in on stdin where input is needed, JSON out on stdout, exit code 0 on succe
 | `attach <intent_id>` | Link more commits, stakeholder references or related intents to an existing record (JSON via stdin) |
 | `show <intent_id>` | Full intent record with commits, stakeholder links and related intents |
 | `lookup <commit> [--vcs name]` | All intents recorded against a commit. Accepts a full hash or a unique prefix of at least 4 characters. Ids are unique per system, not across them, so an id recorded in two systems is reported as ambiguous; name one with `--vcs` |
-| `search <terms...> [--match all]` | Case-insensitive substring search over summary, body, and linked stakeholder URIs and titles, so a ticket key finds its intents |
+| `search <terms...> [--match all]` | Search over summary, body, and linked stakeholder URIs and titles, most relevant first, so a ticket key finds its intents |
 | `by-source <uri> [--contains]` | Intents linked to a stakeholder source, plus the distinct commits across them. `--contains` matches a substring such as a ticket key |
 | `recent [--limit N]` | Newest intents first |
 | `systems` | Known VCS and stakeholder system names |
+| `blame [--format git-porcelain]` | Intents for the commits a blame output names, answered as spans of lines (JSON via stdin, or `git blame --porcelain` output with `--format git-porcelain`) |
 | `backfill` | Recover intent records from a history of commit messages (JSON via stdin) |
 | `serve [--port N]` | Start the web GUI on 127.0.0.1 (default port 4791) |
 
@@ -89,6 +94,79 @@ Options take either `--name value` or `--name=value`. Unknown options and stray
 
 An intent can be recorded before the commit exists and linked with `attach` afterwards. This also covers rebases and squashes, where the same intent ends up on a new hash. One commit can carry several intents and one intent can span several commits.
 
+## Searching
+
+Results come back most relevant first, not newest first, with a term in a summary
+counting for more than the same term somewhere in a long body. Each result carries a
+`snippet`: the part of the body the terms landed in, or the opening of the body when
+the match was a literal one, so a page of hits is readable without opening any of them.
+
+```bash
+intent-record search retry backoff            # either word
+intent-record search retry backoff --match all # both
+intent-record search "retry the fetch"         # the words in that order
+```
+
+A plain word also matches the other forms of itself, so `retry` finds a record that
+said `retried`. A term carrying punctuation is matched as the literal you typed:
+`100%` does not match "100 percent", and `ACME-4` still finds `ACME-42` the way a
+substring search does.
+
+A term can name one field, for when a common word turns up everywhere:
+
+```bash
+intent-record search summary:retry    # summary, body, uri or title
+```
+
+Only those four names count, so a ticket URL is searched as itself rather than read
+as a field called `https`.
+
+## Why is this line here
+
+`lookup` answers for a commit, which means finding the commit first. That is three
+steps: run blame, copy the hash, look it up. `blame` does the whole thing.
+
+```bash
+git blame --porcelain lib/fetch.rb | intent-record blame --format git-porcelain
+git blame --porcelain -L 40,60 lib/fetch.rb | intent-record blame --format git-porcelain
+```
+
+The answer is one entry per change rather than one per line, because neighbouring
+lines from the same change collapse into a span:
+
+```json
+{"spans": [
+  {"from": 40, "to": 44,
+   "asset_version": {"vcs": "git", "external_id": "8f3a1c2d..."},
+   "intents": [{"intent_id": "EUt4WMY", "summary": "Retry flaky fetches with backoff", "...": "..."}]},
+  {"from": 45, "to": 45,
+   "asset_version": {"vcs": "git", "external_id": "b2c4e6f8..."},
+   "intents": []},
+  {"from": 46, "to": 46,
+   "asset_version": {"vcs": "git", "external_id": "0000000000..."},
+   "intents": [], "uncommitted": true}
+]}
+```
+
+A change nothing was recorded against still gets a span, with no intents. A line you
+have edited but not committed is marked `uncommitted`, because there was never
+anything to record against it.
+
+The same change appearing twice in a file with someone else's edit between is
+answered as two spans.
+
+### Other version control systems
+
+`--format git-porcelain` is a convenience. The contract is JSON, and any tool that
+can say which change a line came from can feed it:
+
+```bash
+echo '{"vcs": "perforce", "lines": [{"line": 40, "external_id": "12345"}]}' | intent-record blame
+```
+
+`vcs` defaults to `git`. Line numbers start at 1, and the same line given twice is
+rejected rather than answered from one of the two changes.
+
 ## Backfilling an existing repo
 
 A repo that adopts intent-record already has years of history, and `lookup` and `by-source` answer nothing for any of it. That history is usually exactly what someone needs when they open unfamiliar code. The ticket keys are already in the commit messages, so `backfill` reads them and writes the rows `record` would have written at the time.

data/db/migrate/20260920000001_create_search_index.rb

@@ -0,0 +1,64 @@
+# A relevance index over the text of an intent record. It decides the order the
+# search answers in, never which records the search answers with: FTS5 tokenises,
+# so it cannot see a substring inside a word and it cannot tell `100%` from `100
+# percent`, both of which the substring search is asked for and tested on.
+#
+# Kept in step by triggers rather than from Ruby, so a writer that never heard of
+# the index cannot leave it stale. `backfill` writes through `record` today, but
+# the guarantee should not depend on that staying true.
+class CreateSearchIndex < ActiveRecord::Migration[8.0]
+  TABLE = "intent_search".freeze
+  SOURCE = "intent_records".freeze
+
+  def up
+    # An external-content table: the text lives in intent_records and the index
+    # stores only the terms, so the store does not carry a second copy of every
+    # body.
+    execute(<<~SQL)
+      CREATE VIRTUAL TABLE #{TABLE} USING fts5(
+        summary, body,
+        content='#{SOURCE}', content_rowid='id',
+        tokenize='porter unicode61'
+      )
+    SQL
+
+    create_triggers
+    backfill_existing
+  end
+
+  def down
+    %w[insert update delete].each { |event| execute("DROP TRIGGER IF EXISTS #{TABLE}_after_#{event}") }
+    execute("DROP TABLE IF EXISTS #{TABLE}")
+  end
+
+  private
+
+  # An external-content table is told about a change rather than reading it: the
+  # 'delete' command hands back the old text so FTS5 can retract the terms it
+  # indexed, which is why an update deletes before it inserts.
+  def create_triggers
+    execute(<<~SQL)
+      CREATE TRIGGER #{TABLE}_after_insert AFTER INSERT ON #{SOURCE} BEGIN
+        INSERT INTO #{TABLE}(rowid, summary, body) VALUES (new.id, new.summary, new.body);
+      END
+    SQL
+    execute(<<~SQL)
+      CREATE TRIGGER #{TABLE}_after_delete AFTER DELETE ON #{SOURCE} BEGIN
+        INSERT INTO #{TABLE}(#{TABLE}, rowid, summary, body) VALUES('delete', old.id, old.summary, old.body);
+      END
+    SQL
+    execute(<<~SQL)
+      CREATE TRIGGER #{TABLE}_after_update AFTER UPDATE ON #{SOURCE} BEGIN
+        INSERT INTO #{TABLE}(#{TABLE}, rowid, summary, body) VALUES('delete', old.id, old.summary, old.body);
+        INSERT INTO #{TABLE}(rowid, summary, body) VALUES (new.id, new.summary, new.body);
+      END
+    SQL
+  end
+
+  # A store that already holds records gets them indexed here, so ranking works
+  # on the history from the first run after the upgrade rather than only on what
+  # is written afterwards.
+  def backfill_existing
+    execute("INSERT INTO #{TABLE}(rowid, summary, body) SELECT id, summary, body FROM #{SOURCE}")
+  end
+end

data/lib/intent_record/blame/porcelain.rb

@@ -0,0 +1,37 @@
+module IntentRecord
+  module Blame
+    # Reads `git blame --porcelain` into the lines the command takes.
+    #
+    # The JSON shape is the contract and this is a convenience, so that blaming a
+    # file from a git repository is one command rather than one command and a
+    # converter. Keeping it a separate reader is what stops the store learning
+    # anything about git: it produces the same payload a person could have
+    # written by hand, and a second version control system earns a second reader
+    # rather than a change here.
+    module Porcelain
+      # "<sha> <line in the original file> <line in this file> [<how many
+      # follow>]". The second number is the one a reader is asking about. Content
+      # lines are prefixed with a tab, so a file whose own text looks like a
+      # header is never read as one.
+      HEADER = /\A(?<id>[0-9a-f]{40}|[0-9a-f]{64}) \d+ (?<line>\d+)(?: \d+)?\z/
+
+      module_function
+
+      def lines(text)
+        found = text.to_s.lines.filter_map { |line| header(line) }
+        raise ValidationError, "No blame headers found. Expected `git blame --porcelain` output." if found.empty?
+
+        found
+      end
+
+      def header(line)
+        match = HEADER.match(line.chomp)
+        return nil if match.nil?
+
+        { "line" => match[:line].to_i, "external_id" => match[:id] }
+      end
+
+      private_class_method :header
+    end
+  end
+end

data/lib/intent_record/blame/spans.rb

@@ -0,0 +1,74 @@
+require_relative "../input_validator"
+
+module IntentRecord
+  module Blame
+    # Reads a blame payload into the spans a reader is answered with.
+    #
+    # A blame tool answers per line, and a reader asked about a range. Answering
+    # per line would bury the useful part in repetition, so neighbouring lines
+    # from one change become one span. Neighbouring, not merely equal: the same
+    # change either side of someone else's edit is two places in the file, and
+    # one span across them would claim a line it does not own.
+    #
+    # Nothing here reaches the database, so a malformed payload is refused before
+    # the store is asked anything.
+    class Spans
+      Span = Struct.new(:external_id, :from, :to)
+
+      def initialize(lines)
+        @lines = lines
+      end
+
+      def call
+        collapse(sorted)
+      end
+
+      private
+
+      def sorted
+        raise ValidationError, "At least one line is required" unless @lines.is_a?(Array) && @lines.any?
+
+        entries = @lines.map { |line| entry(line) }.sort_by(&:first)
+        reject_repeats(entries)
+        entries
+      end
+
+      # Sorted, so a repeat is adjacent. The same line attributed to two changes
+      # is a contradiction in the payload, and answering it would mean choosing
+      # one of them silently.
+      def reject_repeats(entries)
+        entries.each_cons(2) do |(earlier, _), (later, _)|
+          raise ValidationError, "Line #{earlier} is given more than once" if earlier == later
+        end
+      end
+
+      def entry(line)
+        raise ValidationError, "Each line needs a line and an external_id" unless line.is_a?(Hash)
+
+        [line_number(line["line"]), InputValidator.required_string!(line, "external_id")]
+      end
+
+      # A string is read in base ten: Integer() on its own reads "010" as
+      # octal and answers about line 8, a wrong answer given confidently. A
+      # fraction is refused rather than truncated for the same reason.
+      def line_number(raw)
+        number = raw.is_a?(Integer) ? raw : Integer(raw.to_s, 10, exception: false)
+        raise ValidationError, "line must be a positive integer, got #{raw.inspect}" if number.nil? || number < 1
+
+        number
+      end
+
+      # Walks in file order, extending the span in hand while the next line both
+      # follows the last one and names the same change.
+      def collapse(entries)
+        entries.each_with_object([]) do |(number, id), spans|
+          extends?(spans.last, number, id) ? spans.last.to = number : spans << Span.new(id, number, number)
+        end
+      end
+
+      def extends?(span, number, id)
+        !span.nil? && span.external_id == id && span.to == number - 1
+      end
+    end
+  end
+end

data/lib/intent_record/cli/blame_input.rb

@@ -0,0 +1,23 @@
+require_relative "../blame/porcelain"
+require_relative "stdin_json"
+
+module IntentRecord
+  class CLI
+    # What `blame` reads from stdin. The JSON shape is the contract; a format
+    # names a reader that produces it from what some blame tool already prints.
+    module BlameInput
+      FORMATS = { "git-porcelain" => Blame::Porcelain }.freeze
+
+      module_function
+
+      def read(format, stdin)
+        return StdinJson.read(stdin) if format.nil?
+
+        reader = FORMATS[format]
+        raise ValidationError, "Unknown --format #{format}. Known formats: #{FORMATS.keys.join(", ")}" if reader.nil?
+
+        { "lines" => reader.lines(stdin.read) }
+      end
+    end
+  end
+end

data/lib/intent_record/cli/dispatch.rb

@@ -11,6 +11,8 @@ require_relative "../commands/recent"
 require_relative "../commands/attach"
 require_relative "../commands/systems"
 require_relative "../commands/backfill"
+require_relative "../commands/blame"
+require_relative "blame_input"
 
 module IntentRecord
   class CLI
@@ -122,6 +124,11 @@ module IntentRecord
         finish! { command.call(stdin_json) }
       end
 
+      def run_blame
+        format = @parser.take_flag("--format")
+        finish! { Commands::Blame.new.call(BlameInput.read(format, @streams.stdin)) }
+      end
+
       def run_systems
         finish! { Commands::Systems.new.call }
       end

data/lib/intent_record/cli/usage.rb

@@ -8,10 +8,11 @@ module IntentRecord
         attach <intent_id>              Link more commits / stakeholder refs / related intents (JSON via stdin)
         show <intent_id>                Full intent record
         lookup <commit> [--vcs name]    Intents recorded against a commit (full hash or unique prefix)
-        search <terms...> [--match all] Substring search over summary and body
+        search <terms...> [--match all] Search over summary, body and ticket links, best match first
         by-source <uri> [--contains]    Intents linked to a stakeholder uri (Jira ticket, Confluence page, ...)
         recent [--limit N]              Newest intents first
         systems                         Known vcs and stakeholder system names
+        blame [--format git-porcelain]  Intents for the commits a blame output names (JSON via stdin)
         backfill [options]              Recover intents from commit messages (JSON via stdin, see below)
         serve [--port N]                Start the local web GUI
 
@@ -28,6 +29,17 @@ module IntentRecord
         --order <which-first>           newest-first (default, as git log prints) or oldest-first
         --dry-run                       Report what it would write, write nothing
 
+      Search terms:
+        Ranked best first. A plain word also matches its other forms, so `retry`
+        finds "retried". A term carrying punctuation is matched literally, so
+        `100%` does not match "100 percent". A term may name one field:
+        summary:retry, body:retry, uri:ACME-42, title:flaky. The name is read in
+        any case. Only those four names count, so a ticket url is searched as itself.
+
+      Input shape for blame (vcs defaults to git):
+        {"vcs": "git", "lines": [{"line": 40, "external_id": "<hash>"}]}
+        With --format git-porcelain, `git blame --porcelain` output goes in as-is.
+
       Input shape for backfill:
         {"commits": [{"commit": "<hash>", "message": "<commit message>",
                       "author": "...", "ref": "<branch name>"}]}

data/lib/intent_record/commands/blame.rb

@@ -0,0 +1,74 @@
+require_relative "../blame/spans"
+require_relative "../blame/porcelain"
+require_relative "../asset_version_normalizer"
+require_relative "../formatter"
+require_relative "../models/asset_version"
+
+module IntentRecord
+  module Commands
+    # Answers "why is this line here" for a range of lines.
+    #
+    # Blame output goes in on stdin rather than the tool shelling out to git, so
+    # the same command answers for Perforce or Mercurial and the store keeps
+    # knowing nothing about which repository a commit belongs to.
+    class Blame
+      DEFAULT_VCS = "git".freeze
+
+      # Git's all-zero object id, which blame gives a line that is in the working
+      # copy and not in the history. It is not a commit, so a reader is told the
+      # line is not committed rather than that nothing was recorded against it,
+      # and the store is not asked about it at all: the id is a valid shape, so
+      # a record can sit under it, and one did, but a line with no history cannot
+      # have had anything recorded against it.
+      # Forty zeros, or sixty-four in a repository using the sha256 object format.
+      UNCOMMITTED = /\A(?:0{40}|0{64})\z/
+
+      def call(input)
+        vcs = AssetVersionNormalizer.vcs_name(input["vcs"] || DEFAULT_VCS)
+        spans = IntentRecord::Blame::Spans.new(input["lines"]).call
+        { "spans" => answers(spans, vcs) }
+      end
+
+      private
+
+      def answers(spans, vcs)
+        known = versions(spans.reject { |span| uncommitted?(span, vcs) }, vcs)
+        spans.map { |span| answer(span, vcs, known[AssetVersionNormalizer.lookup_id(vcs, span.external_id)]) }
+      end
+
+      # Every span is answered, including one whose change the store has never
+      # heard of. Leaving it out would read as "this line has no history", which
+      # is the opposite of what an empty list of intents says.
+      def answer(span, vcs, version)
+        answered = {
+          "from" => span.from,
+          "to" => span.to,
+          "asset_version" => { "vcs" => vcs, "external_id" => span.external_id },
+          "intents" => intents(version)
+        }
+        uncommitted?(span, vcs) ? answered.merge("uncommitted" => true) : answered
+      end
+
+      def uncommitted?(span, vcs)
+        vcs == DEFAULT_VCS && UNCOMMITTED.match?(span.external_id)
+      end
+
+      def intents(version)
+        return [] if version.nil?
+
+        version.intent_records.map { |record| Formatter.full(record) }
+      end
+
+      # Read once for the whole payload rather than per span. A blamed range is a
+      # handful of changes however many lines it covers, and asking per span
+      # would make the query count grow with the size of the range.
+      def versions(spans, vcs)
+        ids = spans.map { |span| AssetVersionNormalizer.lookup_id(vcs, span.external_id) }.uniq
+        scope = Models::AssetVersion.joins(:vcs_system)
+                                    .where(vcs_systems: { name: vcs }, external_id: ids)
+                                    .preload(intent_records: Formatter::PRELOADS)
+        scope.index_by(&:external_id)
+      end
+    end
+  end
+end

data/lib/intent_record/commands/lookup.rb

@@ -14,7 +14,7 @@ module IntentRecord
         version = AssetVersionResolver.new(external_id: @external_id, vcs: @vcs).call
         {
           "asset_version" => Formatter.asset_version(version),
-          "intents" => Formatter.preloaded(version.intent_records.order(:created_at)).map { |r| Formatter.full(r) }
+          "intents" => Formatter.preloaded(version.intent_records).map { |r| Formatter.full(r) }
         }
       end
     end

data/lib/intent_record/commands/search.rb

@@ -1,49 +1,76 @@
 require_relative "../formatter"
-require_relative "../like_pattern"
+require_relative "../match_expression"
+require_relative "../search_membership"
+require_relative "../search_ranking"
+require_relative "../search_snippet"
+require_relative "../search_term"
 require_relative "../models/intent_record"
 
 module IntentRecord
   module Commands
-    # Case-insensitive substring search over summary, body, and linked stakeholder uris and titles,
-    # so a ticket key such as ACME-42 finds the intents built for it.
+    # Search over summary, body, and linked stakeholder uris and titles, so a
+    # ticket key such as ACME-42 finds the intents built for it.
+    #
+    # Which records answer is SearchMembership's decision and what order they
+    # answer in is SearchRanking's. The two are kept apart because they read a
+    # term differently, and only one of them may be trusted with a term that
+    # carries punctuation.
     class Search
       LIMIT = 200
-      FIELDS = %w[intent_records.summary intent_records.body stakeholder_sources.uri stakeholder_sources.title].freeze
+      MATCH_MODES = %w[any all].freeze
 
+      # Refuses bad input here, before the store is asked anything.
       def initialize(terms:, match: "any")
-        @terms = terms.map(&:strip).reject(&:empty?)
+        raw = terms.map(&:strip).reject(&:empty?)
+        raise ValidationError, "At least one search term is required" if raw.empty?
+        raise ValidationError, "--match must be any or all" unless MATCH_MODES.include?(match)
+
+        @terms = raw.map { |term| SearchTerm.parse(term) }
         @match = match
       end
 
       def call
-        raise ValidationError, "At least one search term is required" if @terms.empty?
-        raise ValidationError, "--match must be any or all" unless %w[any all].include?(@match)
-
-        { "intents" => matching_records.map { |r| Formatter.full(r) } }
+        { "intents" => matching_records.map { |r| formatted(r) } }
       end
 
       private
 
+      # The snippet belongs to the search rather than to the record, so it is
+      # merged here instead of in Formatter, which every other command shares.
+      def formatted(record)
+        snippet = SearchSnippet.text(indexed: record[SearchSnippet::COLUMN], body: record.body)
+        Formatter.full(record).merge(SearchSnippet::COLUMN => snippet)
+      end
+
       def matching_records
-        Formatter.preloaded(
-          Models::IntentRecord.left_joins(:stakeholder_sources)
-                              .group("intent_records.id")
-                              .having(having_sql, *having_binds)
-                              .order(created_at: :desc).limit(LIMIT)
-        )
+        Formatter.preloaded(with_ranking(matching_scope))
       end
 
-      def having_sql
-        joiner = @match == "all" ? " AND " : " OR "
-        @terms.map { "SUM(CASE WHEN #{term_clause} THEN 1 ELSE 0 END) > 0" }.join(joiner)
+      def matching_scope
+        Models::IntentRecord.left_joins(:stakeholder_sources)
+                            .group("intent_records.id")
+                            .having(*SearchMembership.new(terms: @terms, match: @match).condition)
+                            .limit(LIMIT)
       end
 
-      def term_clause
-        FIELDS.map { |f| LikePattern.contains(f) }.join(" OR ")
+      # Only the terms the index may answer rank anything. A term it may not be
+      # trusted with would rank by text the person did not ask for, which is the
+      # same reason it does not decide membership either.
+      def indexable
+        @terms.select(&:indexable?)
       end
 
-      def having_binds
-        @terms.flat_map { |t| [LikePattern.contains_bind(t)] * FIELDS.size }
+      # Joins the relevance and fragment the index found, and orders by them.
+      # Terms that hold no searchable token leave nothing to rank, and an empty
+      # MATCH is a syntax error rather than an expression matching nothing, so
+      # that case orders by the tie-break alone and the body stands in for the
+      # fragment.
+      def with_ranking(scope)
+        expression = MatchExpression.for(indexable)
+        return scope.order(Arel.sql(SearchRanking::TIE_BREAK)) if expression.nil?
+
+        join = Models::IntentRecord.sanitize_sql_array([SearchRanking::JOIN, expression])
+        scope.select(SearchRanking::SELECTION).joins(join).order(Arel.sql(SearchRanking::ORDER))
       end
     end
   end

data/lib/intent_record/match_expression.rb

@@ -0,0 +1,50 @@
+module IntentRecord
+  # Turns the terms a user typed into an FTS5 MATCH expression.
+  #
+  # FTS5 reads its right-hand side as an expression language, not as text: `100%`
+  # is a syntax error and a term such as `OR` or `NEAR` is an operator. Quoting
+  # each term makes it a phrase, which is the only form that carries whatever the
+  # user typed through the parser unread.
+  #
+  # Phrases are joined with OR. The expression is used twice, and OR is right
+  # for both: SearchMembership asks the index one term at a time, so an
+  # expression there holds a single phrase and the joiner never applies; and
+  # SearchRanking asks it about every term at once, where a record is scored on
+  # whichever terms it holds rather than dropped for lacking one, because which
+  # records answer has already been settled and AND would score some of them at
+  # nothing.
+  module MatchExpression
+    JOINER = " OR ".freeze
+    QUOTE = '"'.freeze
+
+    module_function
+
+    # Takes SearchTerms, which carry the text and the column the person named.
+    def for(terms)
+      phrases = terms.map { |term| phrase(term) }.compact
+      return nil if phrases.empty?
+
+      phrases.join(JOINER)
+    end
+
+    def phrase(term)
+      # A term of pure punctuation tokenises to nothing, and an empty phrase is
+      # a syntax error rather than a phrase that matches nothing.
+      return nil unless term.text.match?(/[[:alnum:]]/)
+
+      column(term.index_column) + quoted(term.text)
+    end
+
+    # FTS5 reads `summary:"retry"` as that phrase in that column only. A term
+    # naming no column is left unprefixed and is answered over all of them.
+    def column(name)
+      name.nil? ? "" : "#{name}:"
+    end
+
+    def quoted(text)
+      "#{QUOTE}#{text.gsub(QUOTE, QUOTE * 2)}#{QUOTE}"
+    end
+
+    private_class_method :phrase, :column, :quoted
+  end
+end

data/lib/intent_record/models/asset_version.rb

@@ -4,7 +4,9 @@ module IntentRecord
     class AssetVersion < ApplicationRecord
       belongs_to :vcs_system
       has_many :intent_record_asset_versions, dependent: :destroy
-      has_many :intent_records, through: :intent_record_asset_versions
+      # Oldest first, then id, so a commit carrying several intents reads as a
+      # story and the order is the query's rather than the plan's or Ruby's.
+      has_many :intent_records, -> { order(:created_at, :id) }, through: :intent_record_asset_versions
 
       validates :external_id, presence: true, uniqueness: { scope: :vcs_system_id }
     end

data/lib/intent_record/search_index.rb

@@ -0,0 +1,7 @@
+module IntentRecord
+  # The FTS5 table over intent records, created by the migration of the same
+  # name. Named here once, for the two modules that read it.
+  module SearchIndex
+    TABLE = "intent_search".freeze
+  end
+end

data/lib/intent_record/search_membership.rb

@@ -0,0 +1,62 @@
+require_relative "like_pattern"
+require_relative "match_expression"
+require_relative "search_ranking"
+require_relative "search_term"
+
+module IntentRecord
+  # Which records a search answers with.
+  #
+  # Two ways of matching sit behind one condition. Substring matching reads a
+  # term as the literal it is, which is what a person typing `100%` or `ACME-4`
+  # is asking for. The index reads it as a word, which is what finds `retried`
+  # for someone who typed `retry`.
+  #
+  # They are not interchangeable, and the index is the narrower of the two in
+  # one direction and the wider in the other. It cannot see inside a word, so it
+  # would lose `ACME-4` in `ACME-42`; and it drops punctuation, so, measured, it
+  # matches `100 percent` for `100%` and `done now` for `done_now`. A term the
+  # index may not be trusted with therefore gets the substring arm alone, which
+  # SearchTerm#indexable? decides.
+  class SearchMembership
+    JOINERS = { "all" => " AND ", "any" => " OR " }.freeze
+
+    def initialize(terms:, match:)
+      @terms = terms
+      @match = match
+    end
+
+    # Ready for `having`: the condition followed by its binds, in order.
+    def condition
+      clauses = @terms.map { |term| clause(term) }
+      [clauses.map(&:first).join(JOINERS.fetch(@match)), *clauses.flat_map { |c| c.drop(1) }]
+    end
+
+    private
+
+    def clause(term)
+      arms = [substring_arm(term), *index_arm(term)]
+      ["(#{arms.join(" OR ")})", *substring_binds(term), *index_binds(term)]
+    end
+
+    # Counted rather than tested for, because the join to stakeholder_sources
+    # gives a record one row per source and the condition is read after grouping.
+    def substring_arm(term)
+      "SUM(CASE WHEN #{term.fields.map { |f| LikePattern.contains(f) }.join(" OR ")} THEN 1 ELSE 0 END) > 0"
+    end
+
+    def substring_binds(term)
+      [LikePattern.contains_bind(term.text)] * term.fields.size
+    end
+
+    def index_arm(term)
+      return [] unless term.indexable?
+
+      ["EXISTS (SELECT 1 FROM #{SearchRanking::TABLE} " \
+       "WHERE #{SearchRanking::TABLE} MATCH ? AND #{SearchRanking::TABLE}.rowid = intent_records.id)"]
+    end
+
+    def index_binds(term)
+      term.indexable? ? [MatchExpression.for([term])] : []
+    end
+  end
+end

data/lib/intent_record/search_ranking.rb

@@ -0,0 +1,57 @@
+require_relative "search_index"
+require_relative "search_snippet"
+
+module IntentRecord
+  # The order a search answers in.
+  #
+  # Which records match is settled by the substring search, because that is what
+  # a person typing `100%` or `ACME-4` is asking for and FTS5 cannot answer it:
+  # it tokenises, so it neither sees a substring inside a word nor tells `100%`
+  # from `100 percent`. What it can do is say which of the matches the terms are
+  # actually about, and that is all it is asked here.
+  #
+  # bm25 returns a negative score, better the lower, so ascending is best first.
+  # A record the index cannot see scores nothing and sorts after every record it
+  # can, which is the right place for a hit the terms only touch as a substring.
+  module SearchRanking
+    TABLE = SearchIndex::TABLE
+    ALIAS = "ranking".freeze
+
+    # Weights per indexed column, in the order the index declares them. A term in
+    # a one-line summary is a stronger signal than the same term somewhere in a
+    # body that may run for pages, and bm25's own length normalisation does not
+    # say so on its own.
+    SUMMARY_WEIGHT = 10.0
+    BODY_WEIGHT = 1.0
+
+    # Every ranked list needs a total order, or the rows that tie come back in
+    # whatever order the plan produces. Newest first among equals, then id, which
+    # is the order `recent` already answers in.
+    TIE_BREAK = "intent_records.created_at DESC, intent_records.id DESC".freeze
+
+    NO_MATCH_SCORE = 0.0
+
+    # The relevance and the fragment for every record the terms match, computed
+    # once for the search and joined to the candidates. Once, not once per
+    # record: a correlated subquery measured eight seconds for a common word on
+    # twenty-five thousand records, this a quarter of a second. `LIMIT -1` is
+    # what keeps SQLite from flattening the subquery into the outer query, where
+    # bm25 and snippet lose their context; the plan reports it as MATERIALIZE,
+    # and SearchRankingPlanTest holds it there. The `?` is filled by the caller
+    # through sanitize_sql_array.
+    JOIN = <<~SQL.squish.freeze
+      LEFT JOIN (
+        SELECT rowid AS indexed_id,
+               bm25(#{TABLE}, #{SUMMARY_WEIGHT}, #{BODY_WEIGHT}) AS relevance,
+               #{SearchSnippet::EXPRESSION} AS #{SearchSnippet::COLUMN}
+        FROM #{TABLE} WHERE #{TABLE} MATCH ? LIMIT -1
+      ) AS #{ALIAS} ON #{ALIAS}.indexed_id = intent_records.id
+    SQL
+
+    ORDER = "COALESCE(#{ALIAS}.relevance, #{NO_MATCH_SCORE}) ASC, #{TIE_BREAK}".freeze
+
+    # What a search selects when it ranks: the record, and the fragment the
+    # subquery found for it.
+    SELECTION = "intent_records.*, #{ALIAS}.#{SearchSnippet::COLUMN} AS #{SearchSnippet::COLUMN}".freeze
+  end
+end

data/lib/intent_record/search_snippet.rb

@@ -0,0 +1,52 @@
+require_relative "search_index"
+
+module IntentRecord
+  # What a search result shows instead of the whole body.
+  #
+  # A result carries the whole body, which is right for an agent reading one
+  # record and wrong for a person scanning two hundred. The index can say which
+  # part of a body the terms landed in, and that is the part worth reading first.
+  #
+  # It can only say it for a record it matched, though, and a term matched as a
+  # substring inside a longer word is one it never saw. Those fall back to the
+  # opening of the body, so every result carries something rather than leaving a
+  # blank in a list where every other row has text.
+  module SearchSnippet
+    # Roughly a sentence or two either side of the match, which is enough to see
+    # why a record answered without turning the list back into a wall of prose.
+    INDEX_TOKENS = 20
+    FALLBACK_LENGTH = 200
+    ELLIPSIS = "…".freeze
+
+    # Marks are left empty deliberately. A fragment with `[` and `]` around the
+    # match reads as punctuation the writer typed, and a fragment with HTML in it
+    # is either escaped into visible markup or trusted, and neither is wanted.
+    # Column 1 is the body. Evaluated inside SearchRanking's subquery, which is
+    # the one place a search still holds the index's context.
+    EXPRESSION = "snippet(#{SearchIndex::TABLE}, 1, '', '', '#{ELLIPSIS}', #{INDEX_TOKENS})".freeze
+
+    COLUMN = "snippet".freeze
+
+    module_function
+
+    def text(indexed:, body:)
+      return indexed unless indexed.nil? || indexed.empty?
+
+      shortened(body.to_s)
+    end
+
+    # Cut at the last space where there is one, so the reader is not shown a
+    # fragment of a word. Japanese and Chinese prose has no spaces, and neither
+    # does a long url or a hash, and a cut that found no space and kept nothing
+    # showed an ellipsis on its own.
+    def shortened(body)
+      return body if body.length <= FALLBACK_LENGTH
+
+      cut = body[0, FALLBACK_LENGTH]
+      at_word = cut.rpartition(/\s/).first.rstrip
+      "#{at_word.empty? ? cut : at_word}#{ELLIPSIS}"
+    end
+
+    private_class_method :shortened
+  end
+end

data/lib/intent_record/search_term.rb

@@ -0,0 +1,59 @@
+module IntentRecord
+  # One term a person typed, read into the fields it asks about and the text to
+  # look for in them.
+  #
+  # A term may name a field, as in `summary:retry`, for the case where a common
+  # word appears everywhere and ranking it first is not enough. The hazard that
+  # comes with it is that a ticket uri carries a colon too, so only the known
+  # names count as a name and anything else before a colon stays part of the term.
+  class SearchTerm
+    RECORD_FIELDS = { "summary" => "intent_records.summary", "body" => "intent_records.body" }.freeze
+    STAKEHOLDER_FIELDS = { "uri" => "stakeholder_sources.uri", "title" => "stakeholder_sources.title" }.freeze
+    FIELDS = RECORD_FIELDS.merge(STAKEHOLDER_FIELDS).freeze
+    ALL_FIELDS = FIELDS.values.freeze
+
+    # Case-insensitive, as every other name the tool takes is.
+    NAMED = /\A(#{FIELDS.keys.join("|")}):(.*)\z/mi
+
+    # Text the index may be trusted with: letters, digits and the spaces between
+    # them, with at least one letter or digit to tokenise. Anything else the
+    # index would drop, and dropping punctuation is how `100%` comes to match a
+    # record that only ever said `100 percent`.
+    WORD = /\A(?=.*[[:alnum:]])[[:alnum:][:space:]]+\z/
+
+    attr_reader :text, :fields, :index_column
+
+    def self.parse(raw)
+      match = NAMED.match(raw)
+      return new(text: raw, fields: ALL_FIELDS, index_column: nil) if match.nil?
+
+      named(match[1].downcase, match[2])
+    end
+
+    # The shell hands `uri: acme-42` over as one word with the space inside,
+    # and the space is not part of what is being looked for.
+    def self.named(name, text)
+      text = text.strip
+      raise ValidationError, "#{name}: needs something to look for" if text.empty?
+
+      new(text: text, fields: [FIELDS.fetch(name)], index_column: RECORD_FIELDS.key?(name) ? name : nil)
+    end
+
+    def initialize(text:, fields:, index_column:)
+      @text = text
+      @fields = fields
+      @index_column = index_column
+      # Named a stakeholder field, which the index does not hold. Distinguished
+      # from a plain term, where a nil column means every column of the index.
+      @off_index = index_column.nil? && fields != ALL_FIELDS
+    end
+
+    # Whether the index may answer this term at all: not for a field it does
+    # not hold, and not for text it would read differently from the person.
+    def indexable?
+      !@off_index && WORD.match?(text)
+    end
+
+    private_class_method :named
+  end
+end

data/lib/intent_record/version.rb

@@ -1,3 +1,3 @@
 module IntentRecord
-  VERSION = "1.1.0".freeze
+  VERSION = "1.2.0".freeze
 end

data/lib/intent_record/web/views/_intent_cards.erb

@@ -11,7 +11,9 @@
         · <code class="id"><%= h r["intent_id"] %></code>
       </div>
     </header>
-    <div class="body"><%= h r["body"] %></div>
+    <%# A search result carries the fragment its terms landed in; every other
+        page shows one record, where the body is what the reader came for. %>
+    <div class="body"><%= h(r["snippet"] || r["body"]) %></div>
     <% if r["asset_versions"].any? %>
       <div class="links">
         <span class="label">Commits</span>

data/lib/intent_record/web/views/search.erb

@@ -1,5 +1,5 @@
 <header>
   <h1>Search: <%= h query %></h1>
-  <p class="subtitle">Intents whose summary, body, or linked ticket URL or title contain every word</p>
+  <p class="subtitle">Intents matching every word, most relevant first</p>
 </header>
 <%= intent_cards(intents) %>

data/lib/intent_record.rb

@@ -16,6 +16,12 @@ end
 require "intent_record/config"
 require "intent_record/database"
 require "intent_record/global_id"
+require "intent_record/match_expression"
+require "intent_record/search_index"
+require "intent_record/search_ranking"
+require "intent_record/search_term"
+require "intent_record/search_membership"
+require "intent_record/search_snippet"
 require "intent_record/application_record"
 require "intent_record/models/vcs_system"
 require "intent_record/models/asset_version"
@@ -25,5 +31,7 @@ require "intent_record/models/stakeholder_system"
 require "intent_record/models/stakeholder_source"
 require "intent_record/models/stakeholder_reference"
 require "intent_record/models/intent_record_link"
+require "intent_record/blame/spans"
+require "intent_record/blame/porcelain"
 require "intent_record/backfill"
 require "intent_record/cli"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: intent-record
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Erik T. Madsen
@@ -107,6 +107,7 @@ files:
 - LICENSE.txt
 - README.md
 - db/migrate/20260918000001_create_initial_schema.rb
+- db/migrate/20260920000001_create_search_index.rb
 - exe/intent-record
 - lib/intent_record.rb
 - lib/intent_record/application_record.rb
@@ -118,14 +119,18 @@ files:
 - lib/intent_record/backfill/inspection.rb
 - lib/intent_record/backfill/predecessor_finder.rb
 - lib/intent_record/backfill/reference_scanner.rb
+- lib/intent_record/blame/porcelain.rb
+- lib/intent_record/blame/spans.rb
 - lib/intent_record/cli.rb
 - lib/intent_record/cli/argv_parser.rb
+- lib/intent_record/cli/blame_input.rb
 - lib/intent_record/cli/dispatch.rb
 - lib/intent_record/cli/stdin_json.rb
 - lib/intent_record/cli/streams.rb
 - lib/intent_record/cli/usage.rb
 - lib/intent_record/commands/attach.rb
 - lib/intent_record/commands/backfill.rb
+- lib/intent_record/commands/blame.rb
 - lib/intent_record/commands/by_source.rb
 - lib/intent_record/commands/lookup.rb
 - lib/intent_record/commands/recent.rb
@@ -143,6 +148,7 @@ files:
 - lib/intent_record/linkers/asset_version_specs.rb
 - lib/intent_record/linkers/intent_linker.rb
 - lib/intent_record/linkers/stakeholder_linker.rb
+- lib/intent_record/match_expression.rb
 - lib/intent_record/models/asset_version.rb
 - lib/intent_record/models/intent_record.rb
 - lib/intent_record/models/intent_record_asset_version.rb
@@ -151,6 +157,11 @@ files:
 - lib/intent_record/models/stakeholder_source.rb
 - lib/intent_record/models/stakeholder_system.rb
 - lib/intent_record/models/vcs_system.rb
+- lib/intent_record/search_index.rb
+- lib/intent_record/search_membership.rb
+- lib/intent_record/search_ranking.rb
+- lib/intent_record/search_snippet.rb
+- lib/intent_record/search_term.rb
 - lib/intent_record/seeds.rb
 - lib/intent_record/sqlite_connection_setup.rb
 - lib/intent_record/stakeholder_normalizer.rb