woods 1.2.0 → 1.4.0

data/lib/woods/unblocked/document_builder.rb

@@ -10,7 +10,7 @@ module Woods
     # side effects, and structural complexity.
     #
     # @example
-    #   builder = DocumentBuilder.new(repo_url: "https://github.com/bigcartel/admin")
+    #   builder = DocumentBuilder.new(repo_url: "https://github.com/acme/myapp")
     #   doc = builder.build(unit_data)
     #   # => { title: "Order (model)", body: "# Order (model)\n...", uri: "https://..." }
     #
@@ -27,34 +27,66 @@ module Woods
       def build(unit_data)
         type = unit_data['type']
         identifier = unit_data['identifier']
-        file_path = unit_data['file_path']
 
         {
           title: "#{identifier} (#{type})",
           body: build_body(unit_data),
-          uri: build_uri(file_path)
+          uri: uri_for(unit_data)
         }
       end
 
-      private
-
-      def build_uri(file_path)
+      # The citation URI for a unit (GitHub blob URL, or the repo root when the
+      # unit has no file_path). Public so callers can compute a unit's URI
+      # cheaply — e.g. to build the set of currently-existing URIs — without
+      # building the full document body.
+      #
+      # @param unit_data [Hash] Parsed unit JSON (needs 'file_path')
+      # @return [String] Citation URI
+      def uri_for(unit_data)
+        file_path = unit_data['file_path']
         return @repo_url unless file_path
 
         "#{@repo_url}/blob/main/#{file_path}"
       end
 
+      private
+
       def build_body(unit_data)
         type = unit_data['type']
-        case type
-        when 'model' then build_model_body(unit_data)
-        when 'controller' then build_controller_body(unit_data)
-        when 'service', 'job', 'mailer', 'manager', 'decorator', 'concern'
-          build_generic_body(unit_data)
-        when 'graphql', 'graphql_type', 'graphql_mutation', 'graphql_resolver', 'graphql_query'
-          build_graphql_body(unit_data)
-        else build_generic_body(unit_data)
-        end
+        body = case type
+               when 'model' then build_model_body(unit_data)
+               when 'controller' then build_controller_body(unit_data)
+               when 'service', 'job', 'mailer', 'manager', 'decorator', 'concern'
+                 build_generic_body(unit_data)
+               when 'graphql', 'graphql_type', 'graphql_mutation', 'graphql_resolver', 'graphql_query'
+                 build_graphql_body(unit_data)
+               else build_generic_body(unit_data)
+               end
+        # Defensive credential scrub — current builders only emit structured
+        # metadata, but if a future formatter adds source_code or comments
+        # (mirroring Notion's `ModelMapper#extract_description`) the scrub
+        # keeps credential material from reaching Unblocked.
+        redact_credentials(body)
+      end
+
+      # Run the assembled body through CredentialScanner. Fails closed (empty
+      # body) if the scanner raises, so a shipping failure never leaks
+      # unredacted content.
+      #
+      # @param body [String]
+      # @return [String]
+      def redact_credentials(body)
+        return body if body.nil? || body.empty?
+
+        require 'woods/console/credential_scanner'
+        redacted, _counts = credential_scanner.scan(body)
+        redacted
+      rescue StandardError
+        ''
+      end
+
+      def credential_scanner
+        @credential_scanner ||= Woods::Console::CredentialScanner.new
       end
 
       # ── Model formatting ─────────────────────────────────────────────
@@ -100,7 +132,9 @@ module Woods
             dep = a.dig('options', 'dependent')
             dep ? "#{name} (#{dep})" : name
           end
-          lines << "**#{type}:** #{targets.join(', ')}"
+          # Sorted so the body is a function of association content, not order
+          # (the exporter hashes this body to detect changes).
+          lines << "**#{type}:** #{targets.sort.join(', ')}"
         end
 
         lines.join("\n")
@@ -111,7 +145,7 @@ module Woods
         return nil if deps.empty?
 
         grouped = deps.group_by { |d| d['type'] }
-        summary_parts = grouped.map { |type, items| "#{items.size} #{type}s" }
+        summary_parts = grouped.sort_by { |type, _| type.to_s }.map { |type, items| "#{items.size} #{type}s" }
 
         lines = ["## Dependents (#{deps.size} units)"]
         lines << summary_parts.join(', ')
@@ -135,9 +169,9 @@ module Woods
         return nil if controllers.empty? && graphql.empty?
 
         lines = ['## Entry Points']
-        lines << "**Controllers:** #{controllers.map { |c| c['identifier'] }.join(', ')}" if controllers.any?
-        lines << "**GraphQL:** #{graphql.map { |g| g['identifier'] }.join(', ')}" if graphql.any?
-        lines << "**Jobs:** #{jobs.map { |j| j['identifier'] }.join(', ')}" if jobs.any?
+        lines << "**Controllers:** #{controllers.map { |c| c['identifier'] }.sort.join(', ')}" if controllers.any?
+        lines << "**GraphQL:** #{graphql.map { |g| g['identifier'] }.sort.join(', ')}" if graphql.any?
+        lines << "**Jobs:** #{jobs.map { |j| j['identifier'] }.sort.join(', ')}" if jobs.any?
 
         lines.join("\n")
       end
@@ -147,15 +181,16 @@ module Woods
 
         enums = meta['enums']
         if enums.is_a?(Hash) && enums.any?
-          enum_strs = enums.map { |name, values| "#{name} (#{format_enum_values(values)})" }
+          enum_strs = enums.sort_by { |name, _| name.to_s }
+                           .map { |name, values| "#{name} (#{format_enum_values(values)})" }
           parts << "**Enums:** #{enum_strs.join('; ')}"
         end
 
         scopes = meta['scopes']
-        parts << "**Scopes:** #{scopes.map { |s| s['name'] }.join(', ')}" if scopes.is_a?(Array) && scopes.any?
+        parts << "**Scopes:** #{scopes.map { |s| s['name'] }.sort.join(', ')}" if scopes.is_a?(Array) && scopes.any?
 
         concerns = meta['inlined_concerns']
-        parts << "**Concerns:** #{concerns.join(', ')}" if concerns.is_a?(Array) && concerns.any?
+        parts << "**Concerns:** #{concerns.sort.join(', ')}" if concerns.is_a?(Array) && concerns.any?
 
         callbacks = meta['callbacks']
         if callbacks.is_a?(Array) && callbacks.any?
@@ -175,8 +210,8 @@ module Woods
         return nil if jobs.empty? && mailers.empty?
 
         lines = ['## Side Effects']
-        lines << "**Jobs:** #{jobs.map { |j| j['identifier'] }.join(', ')}" if jobs.any?
-        lines << "**Mailers:** #{mailers.map { |m| m['identifier'] }.join(', ')}" if mailers.any?
+        lines << "**Jobs:** #{jobs.map { |j| j['identifier'] }.sort.join(', ')}" if jobs.any?
+        lines << "**Mailers:** #{mailers.map { |m| m['identifier'] }.sort.join(', ')}" if mailers.any?
 
         lines.join("\n")
       end
@@ -204,18 +239,21 @@ module Woods
         routes = meta['routes']
         return nil unless routes.is_a?(Hash) && routes.any?
 
-        lines = ['## Routes']
+        route_lines = []
         routes.each do |action, route_list|
           next unless route_list.is_a?(Array)
 
           route_list.each do |route|
             next unless route.is_a?(Hash)
 
-            lines << "- `#{route['verb']} #{route['path']}` (#{action})"
+            route_lines << "- `#{route['verb']} #{route['path']}` (#{action})"
           end
         end
 
-        lines.size > 1 ? lines.first(20).join("\n") : nil
+        # Sort before truncating so the kept subset is stable across runs.
+        return nil if route_lines.empty?
+
+        (['## Routes'] + route_lines.sort.first(20)).join("\n")
       end
 
       def controller_dependencies(unit)
@@ -225,7 +263,7 @@ module Woods
         models = deps.select { |d| d['type'] == 'model' }.map { |d| d['target'] }
         return nil if models.empty?
 
-        "## Dependencies\n**Models:** #{models.join(', ')}"
+        "## Dependencies\n**Models:** #{models.sort.join(', ')}"
       end
 
       def controller_dependents(unit)
@@ -233,7 +271,7 @@ module Woods
         views = deps.select { |d| d['type'] == 'view_template' }
         return nil if views.empty?
 
-        "## Views\n#{views.map { |v| "- `#{v['identifier']}`" }.first(10).join("\n")}"
+        "## Views\n#{views.map { |v| "- `#{v['identifier']}`" }.sort.first(10).join("\n")}"
       end
 
       # ── GraphQL formatting ───────────────────────────────────────────
@@ -246,7 +284,7 @@ module Woods
 
         deps = unit['dependencies'] || []
         models = deps.select { |d| d['type'] == 'model' }.map { |d| d['target'] }
-        sections << "**Models:** #{models.join(', ')}" if models.any?
+        sections << "**Models:** #{models.sort.join(', ')}" if models.any?
 
         dependents = unit['dependents'] || []
         sections << "**Referenced by:** #{dependents.size} units" if dependents.any?
@@ -267,14 +305,15 @@ module Woods
         deps = unit['dependencies'] || []
         if deps.any?
           by_type = deps.group_by { |d| d['type'] }
-          dep_parts = by_type.map { |type, items| "#{type}: #{items.map { |d| d['target'] }.join(', ')}" }
+          dep_parts = by_type.sort_by { |type, _| type.to_s }
+                             .map { |type, items| "#{type}: #{items.map { |d| d['target'] }.sort.join(', ')}" }
           sections << "## Dependencies\n#{dep_parts.join("\n")}"
         end
 
         dependents = unit['dependents'] || []
         if dependents.any?
           grouped = dependents.group_by { |d| d['type'] }
-          summary = grouped.map { |type, items| "#{items.size} #{type}s" }
+          summary = grouped.sort_by { |type, _| type.to_s }.map { |type, items| "#{items.size} #{type}s" }
           sections << "## Dependents (#{dependents.size})\n#{summary.join(', ')}"
         end
 
@@ -292,9 +331,9 @@ module Woods
       end
 
       def format_callbacks(callbacks)
-        callbacks.first(5).map do |cb|
-          "#{cb['type']}: #{cb['filter']}"
-        end.join(', ')
+        # Sort before truncating so both the selection and order are stable
+        # regardless of input order (the body is hashed for change detection).
+        callbacks.map { |cb| "#{cb['type']}: #{cb['filter']}" }.sort.first(5).join(', ')
       end
     end
   end

data/lib/woods/unblocked/exporter.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require 'set'
+require 'digest'
 require 'woods'
 require_relative 'client'
 require_relative 'rate_limiter'
 require_relative 'document_builder'
+require_relative 'sync_manifest'
 
 module Woods
   module Unblocked
@@ -11,16 +14,27 @@ module Woods
     #
     # Reads extraction output from disk via IndexReader, converts units to
     # condensed Markdown documents, and pushes via the Unblocked Documents API.
-    # All syncs are idempotent — documents are upserted by URI.
+    # Syncs are incremental: a {SyncManifest} records the content hash and
+    # remote document_id of everything last pushed, so each run only PUTs
+    # new/changed documents, skips unchanged ones, and deletes documents whose
+    # source unit has disappeared. Documents are upserted by URI, so a missing
+    # manifest (first run / CI cache miss) degrades to a correct full sync.
     #
     # @example
     #   exporter = Exporter.new(index_dir: "tmp/woods")
     #   stats = exporter.sync_all
-    #   # => { synced: 940, skipped: 5060, errors: [] }
+    #   # => { synced: 12, skipped: 928, deleted: 1, errors: [] }
     #
     class Exporter
       MAX_ERRORS = 100
 
+      # Mass-deletion guard: refuse to purge when more than this fraction of a
+      # manifest of at least PURGE_GUARD_MIN_DOCS entries would be deleted —
+      # the signature of a sync run against a partial index. Override with
+      # force_purge.
+      PURGE_GUARD_FRACTION = 0.30
+      PURGE_GUARD_MIN_DOCS = 10
+
       # Unit types to sync, in priority order.
       # All units are synced for these types.
       FULL_SYNC_TYPES = %w[
@@ -39,9 +53,13 @@ module Woods
       # @param config [Configuration] Woods configuration (default: global config)
       # @param client [Client, nil] Unblocked API client (auto-created from config if nil)
       # @param reader [Object, nil] IndexReader instance (auto-created if nil)
+      # @param manifest [SyncManifest, nil] Sync manifest (auto-created under index_dir if nil)
+      # @param force_full [Boolean] Re-push every unit, ignoring the unchanged check
+      # @param force_purge [Boolean] Bypass the mass-deletion guard
       # @param output [IO] Progress output stream (default: $stdout)
       # @raise [ConfigurationError] if required config is missing
-      def initialize(index_dir:, config: Woods.configuration, client: nil, reader: nil, output: $stdout)
+      def initialize(index_dir:, config: Woods.configuration, client: nil, reader: nil,
+                     manifest: nil, force_full: false, force_purge: false, output: $stdout)
         @collection_id = config.unblocked_collection_id
         raise ConfigurationError, 'unblocked_collection_id is required' unless @collection_id
 
@@ -51,24 +69,37 @@ module Woods
         api_token = config.unblocked_api_token
         raise ConfigurationError, 'unblocked_api_token is required' unless api_token
 
-        budget = ENV.fetch('UNBLOCKED_DAILY_BUDGET', RateLimiter::DEFAULT_BUDGET).to_i
+        budget = ENV.fetch('UNBLOCKED_DAILY_BUDGET', RateLimiter::DEFAULT_BUDGET.to_s).to_i
         limiter = RateLimiter.new(daily_budget: budget)
 
         @client = client || Client.new(api_token: api_token, rate_limiter: limiter)
         @reader = reader || build_reader(index_dir)
         @builder = DocumentBuilder.new(repo_url: repo_url)
+        @manifest = manifest || build_manifest(index_dir)
+        @force_full = force_full
+        @force_purge = force_purge
         @output = output
+        # Initialized here as well as in sync_all so the public sync_type /
+        # sync_type_partial methods work standalone (track_uri needs them).
+        @current_uris = Set.new
+        @budget_exhausted = false
       end
 
       # Sync all configured unit types to the Unblocked collection.
       #
-      # @return [Hash] { synced: Integer, skipped: Integer, errors: Array<String> }
+      # @return [Hash] { synced:, skipped:, deleted:, errors: }
       def sync_all
+        @current_uris = Set.new
+        @budget_exhausted = false
+        reconcile_from_remote if @manifest.empty?
+
         synced = 0
         skipped = 0
         errors = []
 
         FULL_SYNC_TYPES.each do |type|
+          break if @budget_exhausted
+
           result = sync_type(type)
           synced += result[:synced]
           skipped += result[:skipped]
@@ -76,19 +107,24 @@ module Woods
         end
 
         PARTIAL_SYNC_TYPES.each do |type, max_count|
+          break if @budget_exhausted
+
           result = sync_type_partial(type, max_count)
           synced += result[:synced]
           skipped += result[:skipped]
           errors.concat(result[:errors])
         end
 
-        { synced: synced, skipped: skipped, errors: cap_errors(errors) }
+        deleted = @budget_exhausted ? 0 : purge_stale(errors)
+        { synced: synced, skipped: skipped, deleted: deleted, errors: cap_errors(errors) }
+      ensure
+        save_manifest
       end
 
       # Sync all units of a given type.
       #
       # @param type [String] Unit type (e.g. "model", "controller")
-      # @return [Hash] { synced: Integer, skipped: Integer, errors: Array<String> }
+      # @return [Hash] { synced:, skipped:, errors: }
       def sync_type(type)
         units = @reader.list_units(type: type)
         log "  #{type}: #{units.size} units"
@@ -100,7 +136,7 @@ module Woods
       #
       # @param type [String] Unit type
       # @param max_count [Integer] Maximum units to sync
-      # @return [Hash] { synced: Integer, skipped: Integer, errors: Array<String> }
+      # @return [Hash] { synced:, skipped:, errors: }
       def sync_type_partial(type, max_count)
         units = @reader.list_units(type: type)
         return empty_stats if units.empty?
@@ -114,8 +150,14 @@ module Woods
           { entry: entry, data: data, dep_count: dep_count }
         end
 
+        # Every unit of this type still exists — track its URI so partial units
+        # that fall *out* of the top-N are never mistaken for deletions.
+        units_with_data.each { |u| track_uri(u[:data]) }
+
         top_units = units_with_data.sort_by { |u| -u[:dep_count] }.first(max_count)
-        skipped_count = [units.size - max_count, 0].max
+        # Count against what was actually synced — units.size includes entries
+        # whose unit data was missing (dropped by the filter_map above).
+        skipped_count = units.size - top_units.size
 
         log "  #{type}: #{top_units.size}/#{units.size} units (top by dependents)"
 
@@ -138,13 +180,19 @@ module Woods
             next
           end
 
-          push_document(unit_data)
-          synced += 1
+          track_uri(unit_data)
+          if push_document(unit_data) == :skipped
+            skipped += 1
+          else
+            synced += 1
+          end
         rescue Woods::Error => e
           errors << "#{entry['identifier']}: #{e.message}"
-          break if e.message.include?('daily budget exhausted')
+          break if note_budget_exhaustion(e)
         rescue StandardError => e
-          errors << "#{entry['identifier']}: #{e.message}"
+          # Include the class — "undefined method for nil" without it is
+          # unactionable in CI logs.
+          errors << "#{entry['identifier']}: #{e.class}: #{e.message}"
         end
 
         { synced: synced, skipped: skipped, errors: errors }
@@ -156,26 +204,177 @@ module Woods
         errors = []
 
         entries_with_data.each do |entry, unit_data|
-          push_document(unit_data)
-          synced += 1
+          track_uri(unit_data)
+          if push_document(unit_data) == :skipped
+            skipped += 1
+          else
+            synced += 1
+          end
         rescue Woods::Error => e
           errors << "#{entry['identifier']}: #{e.message}"
-          break if e.message.include?('daily budget exhausted')
+          break if note_budget_exhaustion(e)
         rescue StandardError => e
-          errors << "#{entry['identifier']}: #{e.message}"
+          # Include the class — "undefined method for nil" without it is
+          # unactionable in CI logs.
+          errors << "#{entry['identifier']}: #{e.class}: #{e.message}"
         end
 
         { synced: synced, skipped: skipped, errors: errors }
       end
 
+      # Build the document, skip it if the manifest says it is unchanged,
+      # otherwise upsert it and record the new hash + remote document_id.
+      #
+      # @return [Symbol] :synced or :skipped
       def push_document(unit_data)
+        # No file_path → the URI falls back to the bare repo URL, which every
+        # such unit would share: they'd overwrite each other remotely and
+        # ping-pong the manifest hash forever. Skip them.
+        return :skipped unless unit_data['file_path']
+
         doc = @builder.build(unit_data)
-        @client.put_document(
+        # An empty body means the credential scrub failed closed (the builders
+        # always emit at least a header). Upserting it would overwrite a good
+        # remote document with nothing — error out and leave the remote as-is.
+        if doc[:body].nil? || doc[:body].empty?
+          raise Woods::ExtractionError, 'document body empty (credential scrub failure?) — push skipped'
+        end
+
+        hash = fingerprint(doc)
+        return :skipped if !@force_full && @manifest.unchanged?(doc[:uri], hash)
+
+        response = @client.put_document(
           collection_id: @collection_id,
           title: doc[:title],
           body: doc[:body],
           uri: doc[:uri]
         )
+        document_id = (response['id'] if response.is_a?(Hash)) || @manifest.document_id_for(doc[:uri])
+        @manifest.record(uri: doc[:uri], hash: hash, document_id: document_id)
+        :synced
+      end
+
+      # Delete remote documents whose source unit no longer exists. Failures
+      # are appended to +errors+ — a delete that fails silently every run is
+      # how a collection rots while "deleted: 0" looks normal.
+      #
+      # @param errors [Array<String>] sink for delete failures
+      # @return [Integer] number of documents deleted
+      def purge_stale(errors)
+        stale = @manifest.stale_uris(@current_uris)
+        return 0 if stale.empty?
+        return 0 if guard_blocks_purge?(stale)
+
+        resolve_missing_document_ids(stale)
+
+        deleted = 0
+        stale.each do |uri|
+          document_id = @manifest.document_id_for(uri)
+          next unless document_id
+
+          @client.delete_document(document_id: document_id)
+          @manifest.forget(uri)
+          deleted += 1
+        rescue ApiError => e
+          if e.status == 404
+            # Already gone remotely — goal state reached, drop the entry
+            # rather than retrying every run.
+            @manifest.forget(uri)
+          else
+            errors << "delete #{uri}: #{e.message}"
+          end
+        rescue Woods::Error => e
+          break if note_budget_exhaustion(e)
+
+          errors << "delete #{uri}: #{e.message}"
+        rescue StandardError => e
+          # Entry stays in the manifest so a later run retries the delete —
+          # but surface the failure so systematic breakage is visible.
+          errors << "delete #{uri}: #{e.class}: #{e.message}"
+        end
+        deleted
+      end
+
+      # A manifest entry can carry a nil document_id (e.g. the PUT response
+      # body was empty). Those entries would be permanently undeletable, so
+      # before purging, make one bounded all_documents sweep to resolve ids.
+      # Best-effort: unresolved entries are simply skipped by the purge loop.
+      def resolve_missing_document_ids(stale)
+        missing = stale.select { |uri| @manifest.document_id_for(uri).nil? }
+        return if missing.empty?
+
+        ids_by_uri = @client.all_documents(collection_id: @collection_id)
+                            .to_h { |doc| [doc['uri'], doc['id']] }
+        missing.each do |uri|
+          id = ids_by_uri[uri]
+          @manifest.record(uri: uri, hash: nil, document_id: id) if id
+        end
+      rescue StandardError => e
+        log "  id resolution skipped (#{e.message})"
+      end
+
+      # True when purging +stale+ would delete too large a fraction of the
+      # manifest — the signature of running against a partial index. The floor
+      # (PURGE_GUARD_MIN_DOCS) keeps small collections deletable.
+      def guard_blocks_purge?(stale)
+        return false if @force_purge
+
+        size = @manifest.size
+        return false if size < PURGE_GUARD_MIN_DOCS
+
+        fraction = stale.size.to_f / size
+        return false unless fraction > PURGE_GUARD_FRACTION
+
+        log "  WARNING: refusing to delete #{stale.size} of #{size} documents " \
+            "(#{(fraction * 100).round}% > #{(PURGE_GUARD_FRACTION * 100).to_i}% — likely a partial index). " \
+            'Set UNBLOCKED_FORCE_PURGE=1 to override.'
+        true
+      end
+
+      # Seed the manifest from the remote collection when we have no local
+      # state (first run / CI cache miss). The list endpoint returns no body,
+      # so hashes are nil (everything re-pushes), but recovering document_ids
+      # lets this run still purge orphaned documents.
+      #
+      # Auth failures re-raise: a 401/403 here dooms every subsequent call,
+      # and "proceeding with full sync" would burn the whole daily budget on
+      # guaranteed failures.
+      def reconcile_from_remote
+        @client.all_documents(collection_id: @collection_id).each do |doc|
+          uri = doc['uri']
+          next unless uri
+
+          @manifest.record(uri: uri, hash: nil, document_id: doc['id'])
+        end
+      rescue ApiError => e
+        raise if [401, 403].include?(e.status)
+
+        log "  reconcile skipped (#{e.message}) — proceeding with full sync"
+      rescue StandardError => e
+        log "  reconcile skipped (#{e.message}) — proceeding with full sync"
+      end
+
+      def track_uri(unit_data)
+        # Units without a file_path are never pushed (see push_document), so
+        # their fallback repo-root URI must not be marked current either — a
+        # stale repo-root document from before this guard should purge.
+        return unless unit_data['file_path']
+
+        @current_uris << @builder.uri_for(unit_data)
+      end
+
+      def fingerprint(doc)
+        Digest::SHA256.hexdigest("#{doc[:title]}\n#{doc[:body]}")
+      end
+
+      # Records whether an error was a budget-exhaustion stop. Returns true when
+      # it was, so callers can break out of their loop. Class check first; the
+      # message match remains as a fallback for injected clients that raise
+      # plain Woods::Error.
+      def note_budget_exhaustion(error)
+        return false unless error.is_a?(BudgetExhaustedError) || error.message.include?('daily budget exhausted')
+
+        @budget_exhausted = true
       end
 
       def build_reader(index_dir)
@@ -183,6 +382,23 @@ module Woods
         Woods::MCP::IndexReader.new(index_dir)
       end
 
+      # Persist the manifest, downgrading failures to a warning: losing the
+      # manifest only costs a full re-check next run, which must not turn an
+      # otherwise-successful sync into a crash (this runs from an ensure, where
+      # a raise would also mask any in-flight exception).
+      def save_manifest
+        @manifest.save
+      rescue StandardError => e
+        log "  WARNING: sync manifest not persisted (#{e.message}) — next run will re-push all documents"
+      end
+
+      def build_manifest(index_dir)
+        SyncManifest.new(
+          path: File.join(index_dir, 'unblocked_sync_manifest.json'),
+          collection_id: @collection_id
+        )
+      end
+
       def empty_stats
         { synced: 0, skipped: 0, errors: [] }
       end

data/lib/woods/unblocked/rate_limiter.rb

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
+require 'woods'
+
 module Woods
   module Unblocked
+    # Raised when the daily API call budget is exhausted. Subclasses
+    # Woods::Error so existing +rescue Woods::Error+ sites keep working;
+    # callers that need to branch on exhaustion rescue this class instead of
+    # matching the message string.
+    class BudgetExhaustedError < Woods::Error; end
+
     # Daily budget-based rate limiter for the Unblocked API (1000 calls/day).
     #
     # Unlike Notion's per-second throttling, Unblocked limits by daily call count.
@@ -35,13 +43,13 @@ module Woods
       #
       # @yield The API call to execute
       # @return [Object] The block's return value
-      # @raise [Woods::Error] if daily budget is exhausted
+      # @raise [BudgetExhaustedError] if daily budget is exhausted
       def track
         raise ArgumentError, 'block required' unless block_given?
 
         @mutex.synchronize do
           if @calls_today >= @daily_budget
-            raise Woods::Error,
+            raise BudgetExhaustedError,
                   "Unblocked API daily budget exhausted (#{@daily_budget} calls). " \
                   'Budget resets at midnight PST. Use UNBLOCKED_DAILY_BUDGET to adjust.'
           end