Extract optional-file sync context capabilities

docs/adr/2026_09_customisation_and_hidden_file_sync_ownership.md

@@ -21,12 +21,12 @@ reflection. The constructor-name add-on lookup and the `ConfigSync` and
 `HiddenFileSync` add-on identities have been retired.
 
 The Customisation Sync private context coordinates its snapshot operations,
-scan queues, periodic work, and focused transient-state owners. The Hidden File
-Sync private context coordinates reconciliation, periodic work, and the
-lifetimes of focused processed-state, change-processing, and
-conflict-resolution owners. Each receives live settings and database
-projections, focused storage, path, and exact-revision capabilities, and
-explicit host effects rather than `LiveSyncCore`.
+scan queues, periodic work, and focused path and transient-state owners. The
+Hidden File Sync private context coordinates reconciliation, periodic work,
+and the lifetimes of focused path-admission, notification, processed-state,
+change-processing, and conflict-resolution owners. Each receives live settings
+and database projections, focused storage, path, and exact-revision
+capabilities, and explicit host effects rather than `LiveSyncCore`.
 
 The corresponding implemented topology is documented in
 [Optional-file synchronisation architecture](../design_docs/optional_file_sync_architecture.md).
@@ -212,6 +212,19 @@ in-memory projection, while Hidden File Sync markers are persisted operational
 reconciliation state with different identity, invalidation, and deletion
 rules.
 
+`CustomisationSyncPathOperations` binds live configuration-directory, mode,
+and device-name projections to the pure category and V1/V2 key functions. It
+has no host registration or stateful application lifetime. The context uses
+this capability internally; its path helpers are not re-exported through the
+real-Obsidian testing view.
+
+`HiddenFileSyncPathAdmission` owns the ownership-first eligibility sequence
+and its parsed-pattern cache. `HiddenFileSyncChangeNotifier` owns the pending
+folder set, delayed delivery, suppression checks, scheduled-task cancellation,
+and Notice show/hide effect calls. The Obsidian adapter still owns the actual
+Notice instance. These owners make cache and notification behaviour directly
+testable without making either concern a serviceFeature.
+
 `HiddenFileSyncChangeProcessor` owns storage and database change processing,
 the bounded semaphore, same-path event serialisation, activity counts, and the
 inherited order in which processed-state markers and transfer results settle.
@@ -358,13 +371,14 @@ to the non-owner.
 - Replace the complete-core dependency with narrow dependencies.
 
 The private context, path module, codec module, focused presentation view, and
-resource teardown are implemented. A focused catalogue-state owner holds the
-rows, manifests, manifest mtime cache, reactive stores, and update progress,
-while a bounded deduplicator owns recent raw-event keys. Enumeration and scan
-queues remain with the orchestrating context. The context accepts only narrow,
-live projections and explicit effects; an Obsidian adapter at the composition
-edge owns dialogues, Notices, plug-in reload, restart, lifecycle, Vault access,
-and compatibility scan telemetry.
+resource teardown are implemented. A focused path capability binds live
+settings and device identity to the pure path functions. A focused
+catalogue-state owner holds the rows, manifests, manifest mtime cache, reactive
+stores, and update progress, while a bounded deduplicator owns recent raw-event
+keys. Enumeration and scan queues remain with the orchestrating context. The
+context accepts only narrow, live projections and explicit effects; an
+Obsidian adapter at the composition edge owns dialogues, Notices, plug-in
+reload, restart, lifecycle, Vault access, and compatibility scan telemetry.
 
 ### Stage 5: extract the Hidden File Sync runtime — implemented
 
@@ -378,11 +392,14 @@ host-owned command registration, and processor, cache, subscription, and
 Notice teardown are implemented. A focused processed-state owner holds all
 three persisted maps, their key and mtime rules, reset operations, and
 cross-side settlement. Database write and extraction operations consume one
-narrow state port. A focused change processor owns storage and database event
-processing, bounded concurrency, per-path serialisation, activity publication,
-and compatibility settlement order. The context retains scan, initialisation,
-notification, and reconciliation orchestration. A focused conflict-resolution
-owner owns pending-path admission,
+narrow state port. A focused path-admission owner holds the pattern cache and
+the ownership, static-path, pattern, and ignore-file sequence. A focused change
+notifier owns folder batching, delayed delivery, and teardown of its scheduled
+work and Notice effect. A focused change processor owns storage and database
+event processing, bounded concurrency, per-path serialisation, activity
+publication, and compatibility settlement order. The context retains scan,
+initialisation, and reconciliation orchestration. A focused
+conflict-resolution owner owns pending-path admission,
 the parallel classification and serial interaction queues, automatic merge,
 newer-revision selection, interactive JSON application, settlement, and queue
 disposal. An Obsidian adapter owns JSON conflict dialogue instances, progress
@@ -482,11 +499,12 @@ migration without first establishing narrow dependencies.
 - The legacy add-on identity and constructor-name lookup are removed.
 - The two contexts coordinate separate synchronisation workflows, but their
   dependency surfaces are explicit and do not include the complete core.
-  Customisation Sync delegates its derived catalogue and recent-event state,
-  while Hidden File Sync delegates processed-state, change-processing, and
-  conflict lifecycles, to focused owners. Further extraction should follow a
-  concrete behavioural boundary rather than create additional serviceFeatures
-  for private operations.
+  Customisation Sync delegates its path binding, derived catalogue, and
+  recent-event state, while Hidden File Sync delegates path admission,
+  notification, processed-state, change-processing, and conflict lifecycles,
+  to focused owners. Further extraction should follow a concrete behavioural
+  boundary rather than create additional serviceFeatures for private
+  operations.
 
 ## References
 

docs/design_docs/optional_file_sync_architecture.md

@@ -31,6 +31,7 @@ Obsidian composition (`main.ts`)
   |      +--> pure local-path and document routing policy
   |      |
   |      +--> `CustomisationSyncContext`
+  |      |      +-- `CustomisationSyncPathOperations`
   |      |      +-- `CustomisationSyncCatalogueState`
   |      |      +-- recent-event deduplicator
   |      |      +-- immutable service-handler and testing views
@@ -55,6 +56,14 @@ Obsidian composition (`main.ts`)
   |             |      +-- pending paths and two-stage conflict queue
   |             |      +-- automatic and interactive JSON resolution
   |             |
+  |             +--> `HiddenFileSyncPathAdmission`
+  |             |      +-- ownership, path, pattern, and ignore-file admission
+  |             |      +-- per-context parsed-pattern cache
+  |             |
+  |             +--> `HiddenFileSyncChangeNotifier`
+  |             |      +-- changed-folder batching and scheduled delivery
+  |             |      +-- suppression and Notice-effect teardown
+  |             |
   |             +-- immutable service-handler, command, repair, and testing views
   |
   +--> `useCustomisationSyncUI`
@@ -78,13 +87,16 @@ application core.
 | Owner                                 | Owns                                                                                                                                                                                                          | Does not own                                                                                                          |
 | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
 | `useOptionalFileSync`                 | Construction of both contexts, handler registration and removal, local-owner selection, namespace dispatch, compatibility callback order, and context disposal order.                                         | Persisted feature state, synchronisation algorithms, commands, dialogues, or Notices.                                 |
-| `CustomisationSyncContext`            | The `ix:` codec and path rules, scan queues, snapshot storage and application, periodic scan state, and the lifetimes of its transient-state owners.                                                          | Catalogue mutations, recent-event history, Obsidian dialogues, ribbon actions, or handler registration.               |
+| `CustomisationSyncContext`            | The `ix:` scan and snapshot workflow, snapshot storage and application, periodic scan state, and the lifetimes of its focused owners.                                                                         | Path derivation, catalogue mutations, recent-event history, Obsidian dialogues, ribbon actions, or handler registration. |
+| `CustomisationSyncPathOperations`     | Binding live configuration-directory, mode, and device-name projections to the pure category, target-path, V1 key, V2 key, and device-prefix functions.                                                       | I/O, mutable state, local-owner selection, or persistence.                                                             |
 | `CustomisationSyncCatalogueState`     | Transient catalogue rows, manifest lookup and mtime cache, reactive catalogue and manifest stores, and catalogue update progress.                                                                             | Database or storage I/O, scan scheduling, routing, or persistence.                                                    |
 | Customisation Sync event deduplicator | The bounded, newest-first keys used to admit raw configuration events once.                                                                                                                                   | Scheduling, path ownership, catalogue state, or persisted data.                                                       |
-| `HiddenFileSyncContext`               | The `i:` scan and reconciliation workflow, exact-revision repair composition, notification batching, periodic scan state, and focused-owner lifetimes.                                                        | Change-event serialisation, processed-state representation, conflict queue state, Obsidian dialogues, or service handler registration. |
+| `HiddenFileSyncContext`               | The `i:` scan and reconciliation workflow, exact-revision repair composition, periodic scan state, and focused-owner lifetimes.                                                                               | Path admission state, change-event serialisation, processed-state representation, notification batching, conflict queue state, Obsidian dialogues, or service handler registration. |
 | `HiddenFileSyncProcessedState`        | Three device-local autosaved maps, exact storage and database keys, retained known mtime, reset behaviour, and storage/database settlement effects.                                                           | File transfer, scan scheduling, conflict handling, or presentation.                                                   |
 | `HiddenFileSyncChangeProcessor`       | Storage and database change processing, same-path event serialisation, bounded concurrency, activity counts, and the inherited event-consumption and settlement order.                                      | Full scans, initialisation policy, notification presentation, or conflict interaction.                               |
 | `HiddenFileSyncConflictResolution`    | Conflict admission and deduplication, pending paths, the parallel classification and serial interaction queues, automatic merge, newer-revision policy, interactive JSON resolution, and conflict settlement. | Obsidian dialogue instances, general Hidden File Sync scans, processed-state caches, or Service handler registration. |
+| `HiddenFileSyncPathAdmission`         | The ownership-first eligibility sequence, hidden-path and pattern policy, asynchronous ignore-file check, and the per-context parsed-pattern cache.                                                           | Composition-level owner selection, scans, transfer, or persistence.                                                   |
+| `HiddenFileSyncChangeNotifier`        | Changed-folder deduplication, delayed delivery, live suppression and configuration-directory checks, scheduled-task cancellation, and the host Notice show/hide effects.                                     | The Obsidian Notice instance, file extraction, or scan policy.                                                        |
 | Customisation Sync Obsidian adapter   | Obsidian conflict selection, Notice presentation, plug-in reload, restart requests, Vault enumeration, progress telemetry, and platform-derived fallback device names.                                        | Catalogue state, routing, or persisted document operations.                                                           |
 | Hidden File Sync Obsidian adapter     | JSON conflict dialogue lifetime, progress presentation, grouped change Notices, plug-in reload actions, restart scheduling, Vault enumeration, and compatibility activity publication.                        | Transfer, reconciliation, processed-state, or conflict decisions.                                                     |
 | `useCustomisationSyncUI`              | Command, ribbon, dialogue, open-request subscription, and their unload teardown.                                                                                                                              | Synchronisation state or Hidden File Sync initialisation behaviour.                                                   |
@@ -93,9 +105,13 @@ application core.
 The two domain contexts coordinate one cohesive synchronisation workflow each.
 Their private operations and focused owners are not additional serviceFeatures:
 they do not independently register host integration or have separate
-application lifetimes. `HiddenFileSyncChangeProcessor` is a focused resource
-owner because its semaphore, per-path serialisation, activity counters, and
-event settlement form one independently testable lifecycle.
+application lifetimes. `CustomisationSyncPathOperations` is a stateless
+capability which binds live inputs to pure path functions. The Hidden File Sync
+path-admission owner holds the parsed-pattern cache, and its change notifier
+holds the pending folder set and scheduled-task lifetime.
+`HiddenFileSyncChangeProcessor` is a focused resource owner because its
+semaphore, per-path serialisation, activity counters, and event settlement form
+one independently testable lifecycle.
 `HiddenFileSyncConflictResolution` is another focused resource owner because
 conflict admission, pending-path identity, two serialisation stages, and
 disposal form a separate lifecycle.
@@ -112,8 +128,10 @@ than interchangeable state semantics.
 Local file ownership is selected before either context processes an event.
 `optionalFileSyncRouting.ts` combines the configuration directory, feature
 enablement, Customisation Sync mode, and current path category. Hidden File
-Sync target patterns and ignore-file results are evaluated only after the
-static policy selects Hidden File Sync.
+Sync path admission then checks ownership again before reading its current
+target patterns, ignore patterns, or ignore-file result. This keeps the same
+guard available to raw events, scheduled scans, and database reflection
+without duplicating the policy or its cache in the context.
 
 The maintained local ownership is:
 
@@ -187,18 +205,21 @@ also exposes immutable, explicitly internal testing views for maintained
 real-Obsidian contract tests. They provide named operations, including a scoped
 rebuild interceptor, without exposing context instances, dependency objects,
 queues, or writable stores. These test seams are not production service
-locators and should not be used by application features.
+locators and should not be used by application features. Path categorisation
+and key derivation are tested directly through their focused capability rather
+than being re-exported through a broad context testing view.
 
 ## Lifecycle and disposal
 
 The composition is created after the Service Hub and required ServiceModules
 exist, and before lifecycle-driven feature work begins. Each context creates
 its own periodic processor and focused resource owners.
-`CustomisationSyncContext` creates one catalogue-state owner and one
-recent-event deduplicator. `HiddenFileSyncContext` creates one processed-state
-owner before composing database write and extraction operations around its
-narrow port, then creates one change processor and one conflict-resolution
-owner. The change processor owns its semaphore and activity state.
+`CustomisationSyncContext` creates one path capability, one catalogue-state
+owner, and one recent-event deduplicator. `HiddenFileSyncContext` creates one
+path-admission owner, one change notifier, and one processed-state owner before
+composing database write and extraction operations around their narrow ports.
+It then creates one change processor and one conflict-resolution owner. The
+change processor owns its semaphore and activity state.
 Full conflict scans admit discovered paths into the same queue without
 suspending it, so ordinary database conflict notifications continue during a
 slow scan. After enumeration, the operation waits for both classification and
@@ -231,11 +252,13 @@ appropriate, a migration decision.
 
 ## Verification boundaries
 
-Focused unit tests cover routing, semantic handler views, context state
-isolation, teardown, initial cache selection, exact-revision repair, change
-event serialisation and settlement, conflict queue admission, revision
-selection, automatic and interactive merge effect ordering, conflict dialogue
-adaptation, grouped Notices, and compatibility activity publication.
+Focused unit tests cover routing, path-option binding, Hidden File Sync
+admission ordering and cache invalidation, semantic handler views, context
+owner isolation, teardown, initial cache selection, exact-revision repair,
+change-event serialisation and settlement, notification batching, conflict
+queue admission, revision selection, automatic and interactive merge effect
+ordering, conflict dialogue adaptation, grouped Notices, and compatibility
+activity publication.
 The boundary test prevents either domain context from regaining core or
 Obsidian dependencies.