woods 1.6.1 → 2.0.0.beta2

data/lib/woods/notion/exporter.rb

@@ -2,8 +2,12 @@
 
 require 'woods'
 require_relative 'client'
-require_relative 'mapper'
+require_relative 'mappers/shared'
+require_relative 'mappers/model_mapper'
+require_relative 'mappers/column_mapper'
+require_relative 'mappers/migration_mapper'
 require_relative 'rate_limiter'
+require_relative 'sync_manifest'
 
 module Woods
   module Notion
@@ -13,18 +17,60 @@ module Woods
     # to Notion page properties, and pushes via the Notion API. All syncs are idempotent —
     # existing pages are updated, new pages are created.
     #
+    # Syncs are incremental (#207 / B-095): a {SyncManifest} persisted under
+    # the index directory records each page's Notion page_id and a content
+    # hash of its mapped properties, keyed by the page's qualified title
+    # (#149). An unchanged page is skipped with zero API calls; a changed
+    # page is PATCHed directly by its cached page_id (one call, no
+    # find-by-title query); only a manifest miss pays the full lookup /
+    # legacy-adoption / create path. A cold manifest (first run, deleted
+    # file) therefore degrades to exactly the pre-manifest behavior, plus
+    # manifest writes. Set +WOODS_NOTION_FORCE=1+ (or pass
+    # +force_full: true+) to ignore the manifest for one run.
+    #
     # @example
     #   exporter = Exporter.new(index_dir: "tmp/woods")
     #   stats = exporter.sync_all
-    #   # => { data_models: 10, columns: 45, errors: [] }
+    #   # => { data_models: 10, columns: 45, skipped: 0, errors: [] }
     #
-    class Exporter # rubocop:disable Metrics/ClassLength
+    # rubocop:disable-next Metrics/ClassLength
+    class Exporter
+      MAX_ERRORS = 100
+
+      # Manifest scope for the Data Models database.
+      SCOPE_DATA_MODELS = 'data_models'
+      # Manifest scope for the Columns database.
+      SCOPE_COLUMNS = 'columns'
+      # Manifest file name, stored under the index/output directory
+      # (mirrors Unblocked's +unblocked_sync_manifest.json+).
+      MANIFEST_FILENAME = 'notion_sync_manifest.json'
+      # Escape hatch: set to 1/true/yes to ignore the manifest for one run
+      # (the Notion counterpart of +UNBLOCKED_FORCE_FULL_SYNC+). Read here
+      # rather than in the rake task so the MCP notion tool and embedded
+      # callers honor it too.
+      FORCE_ENV_VAR = 'WOODS_NOTION_FORCE'
+
+      # Client errors that mean a cached page is gone (deleted or archived
+      # behind the manifest), so the sync should self-heal by recreating it.
+      # {Client} raises untyped +Woods::Error+ with the Notion status code
+      # baked into the message ("Notion API error 404: ..."), so this is a
+      # message-level match: 404/410 (page gone) or an archived-page
+      # complaint (Notion answers 400 "Can't update a page that is
+      # archived..." for trashed pages).
+      STALE_PAGE_ERROR = /\ANotion API error (?:404|410)\b|archiv/i
+
       # @param index_dir [String] Path to extraction output directory
       # @param config [Configuration] Woods configuration (default: global config)
       # @param client [Client, nil] Notion API client (auto-created from config if nil)
       # @param reader [Object, nil] IndexReader instance (auto-created from index_dir if nil)
+      # @param manifest [SyncManifest, nil] Sync manifest (auto-created under index_dir if nil)
+      # @param force_full [Boolean, nil] Ignore the manifest for this run —
+      #   every page goes through the full find-by-title path (results are
+      #   still recorded). Defaults to the {FORCE_ENV_VAR} env flag.
       # @raise [ConfigurationError] if notion_api_token is not configured
-      def initialize(index_dir:, config: Woods.configuration, client: nil, reader: nil)
+      # rubocop:disable-next Metrics/ParameterLists -- injectable collaborators, mirrors Unblocked::Exporter
+      def initialize(index_dir:, config: Woods.configuration, client: nil, reader: nil,
+                     manifest: nil, force_full: nil)
         # A non-blank NOTION_API_TOKEN overrides the configured token
         # (documented contract; also what the MCP notion_wired? gate keys on).
         # Resolve via the shared Woods.resolve_notion_token so the exporter,
@@ -37,61 +83,104 @@ module Woods
         @database_ids = config.notion_database_ids || {}
         @client = client || Client.new(api_token: api_token)
         @reader = reader || build_reader(index_dir)
+        @manifest = manifest || build_manifest(index_dir)
+        @force_full = force_full.nil? ? env_force? : force_full
         @page_id_cache = {}
       end
 
-      # Sync all configured databases. Idempotent — safe to re-run.
+      # Sync all configured databases. Idempotent — safe to re-run; a re-run
+      # against an unchanged index issues zero API calls (see class docs).
       #
-      # @return [Hash] { data_models: Integer, columns: Integer, errors: Array<String> }
+      # @return [Hash] { data_models: Integer, columns: Integer,
+      #   skipped: Integer, errors: Array<String> }
       def sync_all
-        model_stats = @database_ids[:data_models] ? sync_data_models : empty_stats
-        column_stats = @database_ids[:columns] && @database_ids[:data_models] ? sync_columns : empty_stats
-
-        all_errors = model_stats[:errors] + column_stats[:errors]
-
-        {
-          data_models: model_stats[:synced],
-          columns: column_stats[:synced],
-          errors: cap_errors(all_errors)
-        }
+        with_pinned_index do
+          model_stats = @database_ids[:data_models] ? sync_data_models : empty_stats
+          warn_columns_without_data_models if @database_ids[:columns] && !@database_ids[:data_models]
+          column_stats = @database_ids[:columns] ? sync_columns : empty_stats
+
+          all_errors = model_stats[:errors] + column_stats[:errors]
+
+          {
+            data_models: model_stats[:synced],
+            columns: column_stats[:synced],
+            skipped: model_stats[:skipped] + column_stats[:skipped],
+            errors: cap_errors(all_errors)
+          }
+        end
       end
 
       # Sync model units to the Data Models Notion database.
       #
-      # @return [Hash] { synced: Integer, errors: Array<String> }
+      # Pages are titled with the table name. When several models share one
+      # table (STI hierarchies, custom +self.table_name+ overlaps) a bare
+      # table-name title makes each model overwrite the others' pages (#149),
+      # so those titles are qualified as "<table> (<ModelName>)". Models with
+      # a unique table keep the bare title — no churn for the common case.
+      #
+      # Manifest entries whose title vanished from the current model set are
+      # pruned afterwards; the Notion pages themselves are left alone (no
+      # deletion path exists, and none is invented here).
+      #
+      # @return [Hash] { synced: Integer, skipped: Integer, errors: Array<String> }
       def sync_data_models
         database_id = @database_ids[:data_models]
         return empty_stats unless database_id
 
-        migration_dates = load_migration_dates
-        sync_units('model', database_id, 'Table Name') do |unit_data|
-          properties = Mappers::ModelMapper.new.map(unit_data)
-          enrich_with_migration_date(properties, migration_dates)
-          properties
+        begin
+          migration_dates = load_migration_dates
+          shared_tables = shared_table_names
+          stats = sync_units('model', database_id, 'Table Name', SCOPE_DATA_MODELS) do |unit_data|
+            properties = Mappers::ModelMapper.new.map(unit_data)
+            # Enrichment reads the bare table name from the title — run it
+            # before any qualification rewrites the title.
+            enrich_with_migration_date(properties, migration_dates)
+            legacy_title = qualify_shared_table_title(properties, unit_data, shared_tables)
+            [properties, legacy_title]
+          end
+          @manifest.prune(SCOPE_DATA_MODELS, stats.delete(:current_keys))
+          stats
+        ensure
+          save_manifest
         end
       end
 
       # Sync column data to the Columns Notion database.
       #
-      # @return [Hash] { synced: Integer, errors: Array<String> }
+      # Columns are synced **per physical table**, not per model. Column pages
+      # are titled "<table>.<column>", so two models sharing a table (STI, a
+      # shared +self.table_name=+) produced one page from two different
+      # payloads and PATCHed it back and forth on every run, forever (EXP-1).
+      # Grouping first means one page per physical column per run, with the
+      # Table relation listing every owning model and the validations unioned.
+      #
+      # Manifest entries whose qualified title vanished from the current
+      # column set are pruned afterwards; the Notion pages themselves are
+      # left alone (no deletion path exists, and none is invented here).
+      #
+      # @return [Hash] { synced: Integer, skipped: Integer, errors: Array<String> }
       def sync_columns
         database_id = @database_ids[:columns]
         return empty_stats unless database_id
 
-        synced = 0
-        errors = []
+        begin
+          totals = { synced: 0, skipped: 0, errors: [] }
+          current_keys = []
 
-        each_model_unit do |entry, unit_data|
-          synced_count, unit_errors = sync_model_columns(entry, unit_data, database_id)
-          synced += synced_count
-          errors.concat(unit_errors)
-        end
+          column_groups.each do |group|
+            result = sync_table_columns(group, database_id, current_keys)
+            totals[:synced] += result[:synced]
+            totals[:skipped] += result[:skipped]
+            totals[:errors].concat(result[:errors])
+          end
 
-        { synced: synced, errors: errors }
+          @manifest.prune(SCOPE_COLUMNS, current_keys)
+          totals
+        ensure
+          save_manifest
+        end
       end
 
-      MAX_ERRORS = 100
-
       private
 
       # Sync all units of a type, yielding each for property mapping.
@@ -99,28 +188,39 @@ module Woods
       # @param type [String] Unit type to list
       # @param database_id [String] Notion database UUID
       # @param title_property [String] Name of the title property
-      # @yield [Hash] Unit data hash, expects Notion properties hash back
-      # @return [Hash] { synced: Integer, errors: Array<String> }
-      def sync_units(type, database_id, title_property)
-        synced = 0
-        errors = []
+      # @param scope [String] Manifest scope for this database
+      # @yield [Hash] Unit data hash; expects back +[properties, legacy_title]+
+      #   where +legacy_title+ (String, nil) is a pre-qualification title an
+      #   already-synced page may still carry (see {#adopt_legacy_page})
+      # @return [Hash] { synced:, skipped:, errors:, current_keys: }
+      def sync_units(type, database_id, title_property, scope)
+        stats = { synced: 0, skipped: 0, errors: [], current_keys: [] }
 
         @reader.list_units(type: type).each do |entry|
           unit_data = @reader.find_unit(entry['identifier'])
           next unless unit_data
 
           begin
-            properties = yield(unit_data)
+            properties, legacy_title = yield(unit_data)
             title_value = extract_title_text(properties[title_property])
-            page_id = upsert_page(database_id: database_id, title_value: title_value, properties: properties)
+            stats[:current_keys] << title_value
+            legacy = legacy_title ? { title: legacy_title } : nil
+            status, page_id = sync_page(scope: scope, database_id: database_id, title_value: title_value,
+                                        properties: properties, legacy: legacy)
             @page_id_cache[entry['identifier']] = page_id
-            synced += 1
+            stats[status] += 1
+          rescue AuthenticationError
+            # Not a per-unit failure: the token is wrong or the integration is
+            # not shared with this database, so every remaining call in the run
+            # would fail too — at Notion's 3 req/sec. Abort instead of spending
+            # the whole sync proving it.
+            raise
           rescue StandardError => e
-            errors << "#{entry['identifier']}: #{e.message}"
+            stats[:errors] << "#{entry['identifier']}: #{e.message}"
           end
         end
 
-        { synced: synced, errors: errors }
+        stats
       end
 
       # Iterate over loaded model units.
@@ -135,27 +235,189 @@ module Woods
         end
       end
 
-      # Sync columns for a single model.
+      # Run a multi-read export body against one index generation.
+      #
+      # Every public IndexReader accessor self-refreshes when the published
+      # generation moves, and the reader assigns pinning responsibility to
+      # direct callers. Unpinned, a concurrent extraction mid-sync means the
+      # model list, the unit bodies and the page-id cache can straddle two
+      # generations (EXP-5) — a model present only in the newer one gets a nil
+      # parent page and a run of avoidable churn.
+      #
+      # Guarded by +respond_to?+: injected readers (specs, embedders) need not
+      # implement pinning.
+      #
+      # @yield the export body
+      # @return [Object] the block's value
+      def with_pinned_index(&block)
+        return yield unless @reader.respond_to?(:with_pinned_generation)
+
+        @reader.with_pinned_generation(&block)
+      end
+
+      # A columns-only configuration used to make {#sync_all} return all-zero
+      # stats in silence, which is indistinguishable from breakage (EXP-11).
+      # The sync runs; only the Table relation is unavailable, because its
+      # target pages live in the Data Models database nobody configured.
       #
-      # @return [Array(Integer, Array<String>)] Count of synced columns and errors
-      def sync_model_columns(entry, unit_data, database_id)
-        parent_page_id = @page_id_cache[entry['identifier']]
-        columns = unit_data.dig('metadata', 'columns') || []
-        validations = unit_data.dig('metadata', 'validations') || []
+      # @return [void]
+      def warn_columns_without_data_models
+        warn 'woods: notion sync has no data_models database configured — ' \
+             'syncing columns without a Table relation'
+      end
+
+      # One entry per physical table: every model that owns it, the union of
+      # their columns and validations, and the Data Models pages the Table
+      # relation should list.
+      #
+      # Parent page ids come from the page-id cache, which the manifest skip
+      # path populates too — so on a warm run the Table relation is
+      # byte-identical to the previous run and unchanged columns hash stable.
+      # Owners and page ids are sorted so the payload does not depend on the
+      # order the index happens to list models in.
+      #
+      # @return [Array<Hash>] { table_name:, owners:, columns:, validations:,
+      #   parent_page_ids: }
+      def column_groups
+        groups = {}
+        each_model_unit { |entry, unit_data| absorb_into_column_group(groups, entry, unit_data) }
+        groups.each_value { |group| finalize_column_group(group) }
+        groups.values
+      end
+
+      # Fold one model's columns and validations into its table's group.
+      #
+      # @return [void]
+      def absorb_into_column_group(groups, entry, unit_data)
+        table_name = Mappers::ModelMapper.table_name_for(unit_data)
+        group = (groups[table_name] ||= { table_name: table_name, owners: [], columns: {}, validations: [] })
+        group[:owners] << entry['identifier']
+        (unit_data.dig('metadata', 'columns') || []).each { |column| group[:columns][column['name']] ||= column }
+        group[:validations].concat(unit_data.dig('metadata', 'validations') || [])
+      end
+
+      # Sort and dedupe a group so its payload does not depend on the order
+      # the index happens to list models in.
+      #
+      # @return [void]
+      def finalize_column_group(group)
+        group[:owners] = group[:owners].uniq.sort
+        group[:validations] = group[:validations].uniq
+        group[:parent_page_ids] = group[:owners].filter_map { |owner| @page_id_cache[owner] }.uniq
+      end
+
+      # Sync the columns of one physical table.
+      #
+      # Column pages are titled "<table>.<column>" (#149). Every model shares
+      # id/created_at/updated_at, and upserting by the bare column name found
+      # the previous model's page by title equality across the whole Columns
+      # database — churning it down to one page per distinct column name.
+      # The table qualifier comes from {Mappers::ModelMapper.table_name_for},
+      # the same value the Table relation's target page is titled with.
+      #
+      # @param group [Hash] One {#column_groups} entry
+      # @param current_keys [Array<String>] Sink for this run's column titles
+      # @return [Hash] { synced: Integer, skipped: Integer, errors: Array<String> }
+      def sync_table_columns(group, database_id, current_keys)
         mapper = Mappers::ColumnMapper.new
-        synced = 0
-        errors = []
-
-        columns.each do |column|
-          properties = mapper.map(column, model_identifier: entry['identifier'],
-                                          validations: validations, parent_page_id: parent_page_id)
-          upsert_page(database_id: database_id, title_value: column['name'], properties: properties)
-          synced += 1
+        stats = { synced: 0, skipped: 0, errors: [] }
+        owners = group[:owners].join(', ')
+
+        group[:columns].each_value do |column|
+          stats[sync_one_column(mapper, group, column, database_id, current_keys)] += 1
+        rescue AuthenticationError
+          raise # see sync_units — an auth failure dooms the whole run
         rescue StandardError => e
-          errors << "#{entry['identifier']}.#{column['name']}: #{e.message}"
+          stats[:errors] << "#{owners}.#{column['name']}: #{e.message}"
+        end
+
+        stats
+      end
+
+      # Sync one physical column's page.
+      #
+      # @return [Symbol] :synced or :skipped
+      def sync_one_column(mapper, group, column, database_id, current_keys)
+        properties = mapper.map(column, model_identifier: group[:owners].first, table_name: group[:table_name],
+                                        validations: group[:validations],
+                                        parent_page_ids: group[:parent_page_ids])
+        title_value = extract_title_text(properties['Column Name'])
+        current_keys << title_value
+        status, = sync_page(scope: SCOPE_COLUMNS, database_id: database_id, title_value: title_value,
+                            properties: properties,
+                            legacy: column_legacy_descriptor(column, group[:parent_page_ids].first))
+        status
+      end
+
+      # Sync one page through the manifest. Three tiers, cheapest first:
+      # manifest hit with an unchanged hash — skip, zero API calls; hit with
+      # a changed hash — PATCH the cached page_id directly (one call, with
+      # gone-page self-heal); miss — the full #149 path ({#upsert_page}:
+      # find by qualified title, legacy adoption, create/update). Every
+      # non-skip outcome records page_id + content hash for the next run.
+      # +force_full+ bypasses the manifest reads entirely (tier three for
+      # everything) but still records.
+      #
+      # @param scope [String] Manifest scope
+      # @param database_id [String] Notion database UUID
+      # @param title_value [String] Qualified title — the manifest key
+      # @param properties [Hash] Full property payload to write
+      # @param legacy [Hash, nil] Legacy descriptor for {#upsert_page}
+      # @return [Array(Symbol, String)] [:skipped or :synced, page id]
+      def sync_page(scope:, database_id:, title_value:, properties:, legacy: nil)
+        content_hash = SyncManifest.content_hash(properties)
+
+        unless @force_full
+          if @manifest.unchanged?(scope, title_value, content_hash)
+            return [:skipped, @manifest.page_id_for(scope, title_value)]
+          end
+
+          cached_id = @manifest.page_id_for(scope, title_value)
+          if cached_id && (page_id = update_cached_page(scope, title_value, cached_id, properties))
+            @manifest.record(scope: scope, key: title_value, hash: content_hash, page_id: page_id)
+            return [:synced, page_id]
+          end
         end
 
-        [synced, errors]
+        page_id = upsert_page(database_id: database_id, title_value: title_value,
+                              properties: properties, legacy: legacy)
+        @manifest.record(scope: scope, key: title_value, hash: content_hash, page_id: page_id)
+        [:synced, page_id]
+      end
+
+      # PATCH a page by its manifest-cached id — the one-call path for
+      # changed content. When Notion reports the page gone ({STALE_PAGE_ERROR}:
+      # deleted or archived behind the cache), warn once, drop the manifest
+      # entry, and return nil so the caller falls through to the create path
+      # (self-heal). Any other API failure propagates to the per-unit rescue
+      # so it lands in the error list with the entry retained for a retry.
+      #
+      # @return [String, nil] the page id on success, nil when the cached page is gone
+      def update_cached_page(scope, key, page_id, properties)
+        @client.update_page(page_id: page_id, properties: properties)
+        page_id
+      rescue Woods::Error => e
+        raise unless e.message.match?(STALE_PAGE_ERROR)
+
+        warn "woods: notion sync cached page #{page_id} for #{key.inspect} is gone (#{e.message}) — recreating"
+        @manifest.forget(scope, key)
+        nil
+      end
+
+      # Describe the pre-#149 page a column may still be stored under: the
+      # bare column name, verified against this model's Table relation when
+      # the parent Data Models page is known.
+      #
+      # @param column [Hash]
+      # @param parent_page_id [String, nil]
+      # @return [Hash] Legacy descriptor for {#upsert_page}
+      def column_legacy_descriptor(column, parent_page_id)
+        legacy = { title: column['name'].to_s }
+        if parent_page_id
+          legacy[:relation_property] = 'Table'
+          legacy[:relation_page_id] = parent_page_id
+        end
+        legacy
       end
 
       # Enrich model properties with migration date if available.
@@ -182,9 +444,22 @@ module Woods
 
       # Upsert a Notion page: find by title, update if exists, create if not.
       #
+      # When the qualified-title lookup misses and a +legacy+ descriptor is
+      # given, a page still carrying the pre-qualification title may be
+      # adopted instead of creating a duplicate (see {#adopt_legacy_page}).
+      # Updating the adopted page rewrites its title to the qualified form,
+      # so the legacy lookup is a one-time migration cost per page.
+      #
+      # @param database_id [String] Notion database UUID
+      # @param title_value [String] Title to find the page by
+      # @param properties [Hash] Full property payload to write
+      # @param legacy [Hash, nil] { title:, relation_property:, relation_page_id: }
       # @return [String] Notion page ID
-      def upsert_page(database_id:, title_value:, properties:)
+      def upsert_page(database_id:, title_value:, properties:, legacy: nil)
         existing = @client.find_page_by_title(database_id: database_id, title: title_value)
+        if existing.nil? && legacy && legacy[:title] != title_value
+          existing = adopt_legacy_page(database_id: database_id, legacy: legacy, new_title: title_value)
+        end
 
         if existing
           @client.update_page(page_id: existing['id'], properties: properties)
@@ -195,9 +470,129 @@ module Woods
         end
       end
 
+      # Locate a page still titled with the pre-#149 (unqualified) title so
+      # the sync can adopt it — update it in place, which also rewrites its
+      # title to the qualified form — rather than strand it next to a fresh
+      # duplicate forever.
+      #
+      # Adoption is deliberately conservative:
+      # - With a relation qualifier (Columns), the title-equality filter is
+      #   AND-ed with a `relation contains` filter on the parent Data Models
+      #   page, so only a legacy page actually belonging to this model can be
+      #   adopted. Multiple matches are same-parent duplicates; the first is
+      #   adopted with a warning.
+      # - Without one (Data Models), the page is adopted only when exactly one
+      #   match exists; an ambiguous set is left alone with a warning and a
+      #   fresh qualified page is created instead.
+      #
+      # @param database_id [String] Notion database UUID
+      # @param legacy [Hash] { title:, relation_property:, relation_page_id: }
+      # @param new_title [String] Qualified title the adopted page will get
+      # @return [Hash, nil] Adoptable page, or nil to create fresh
+      def adopt_legacy_page(database_id:, legacy:, new_title:)
+        results = query_legacy_pages(database_id, legacy)
+        return nil if results.empty?
+
+        if results.size > 1
+          return warn_ambiguous_legacy(legacy, results) unless legacy[:relation_page_id]
+
+          warn "woods: notion sync found #{results.size} legacy pages titled #{legacy[:title].inspect} " \
+               "for one Table relation; adopting the first (#{results.first['id']})"
+        end
+
+        warn "woods: notion sync adopting legacy page #{results.first['id']} " \
+             "(#{legacy[:title].inspect} -> #{new_title.inspect})"
+        results.first
+      end
+
+      # @param legacy [Hash]
+      # @param results [Array<Hash>]
+      # @return [nil]
+      def warn_ambiguous_legacy(legacy, results)
+        warn "woods: notion sync found #{results.size} pages sharing the legacy title " \
+             "#{legacy[:title].inspect} and cannot tell them apart; creating a qualified page " \
+             'instead — clean up the legacy pages manually'
+        nil
+      end
+
+      # Query pages carrying the legacy title, narrowed by the parent relation
+      # when the descriptor names one. This is the only extra API call the
+      # qualified-title scheme introduces, and it runs solely on the
+      # qualified-lookup miss path.
+      #
+      # @param database_id [String]
+      # @param legacy [Hash]
+      # @return [Array<Hash>] Matching pages
+      def query_legacy_pages(database_id, legacy)
+        filter = { property: 'title', title: { equals: legacy[:title] } }
+        if legacy[:relation_property] && legacy[:relation_page_id]
+          filter = { and: [filter, { property: legacy[:relation_property],
+                                     relation: { contains: legacy[:relation_page_id] } }] }
+        end
+
+        response = @client.query_database(database_id: database_id, filter: filter)
+        response['results'] || []
+      end
+
+      # Table names claimed by more than one model unit in the index — STI
+      # hierarchies, or models sharing a table via +self.table_name=+.
+      #
+      # @return [Array<String>]
+      def shared_table_names
+        counts = Hash.new(0)
+        each_model_unit do |_entry, unit_data|
+          counts[Mappers::ModelMapper.table_name_for(unit_data)] += 1
+        end
+        counts.select { |_table, count| count > 1 }.keys
+      end
+
+      # Rewrite the Data Models title to "<table> (<ModelName>)" for a model
+      # whose table name is shared with another model, so the two stop
+      # overwriting each other's pages (#149).
+      #
+      # @param properties [Hash] Mapped Notion properties (mutated)
+      # @param unit_data [Hash]
+      # @param shared_tables [Array<String>]
+      # @return [String, nil] The bare table name as the legacy title when
+      #   qualification was applied, nil otherwise
+      def qualify_shared_table_title(properties, unit_data, shared_tables)
+        table_name = Mappers::ModelMapper.table_name_for(unit_data)
+        return nil unless shared_tables.include?(table_name)
+
+        qualified = "#{table_name} (#{unit_data['identifier']})"
+        properties['Table Name'] = { title: [{ text: { content: qualified } }] }
+        table_name
+      end
+
+      # Persist the manifest, downgrading failures to a warning: a lost
+      # manifest only costs a full re-check next run, which must not turn an
+      # otherwise-successful sync into a crash (called from ensure blocks,
+      # where a raise would also mask any in-flight exception).
+      #
+      # @return [void]
+      def save_manifest
+        @manifest.save
+      rescue StandardError => e
+        warn "woods: notion sync manifest not persisted (#{e.message}) — next run re-checks every page"
+      end
+
+      # @param index_dir [String]
+      # @return [SyncManifest]
+      def build_manifest(index_dir)
+        SyncManifest.new(path: File.join(index_dir, MANIFEST_FILENAME), database_ids: @database_ids)
+      end
+
+      # Truthy set mirrors the rake tasks' env_flag convention, so
+      # WOODS_NOTION_FORCE=false / =0 disables rather than silently enabling.
+      #
+      # @return [Boolean]
+      def env_force?
+        %w[1 true yes].include?(ENV.fetch(FORCE_ENV_VAR, '').strip.downcase)
+      end
+
       # @return [Hash]
       def empty_stats
-        { synced: 0, errors: [] }
+        { synced: 0, skipped: 0, errors: [] }
       end
 
       # Cap errors to prevent unbounded memory growth.