[OpenSpec] sources-sftp-adapter-intake-hand-over #2551

⚠️ OpenSpec-managed issue — this content is automatically synced
from the openspec/ directory. Manual edits will be overwritten on next sync.

Artifacts

• ✅ Metadata
• ✅ Proposal
• ✅ Specs
• 🔲 Design
• ✅ Tasks
• 🔲 Plan
• 🔲 Review

Summary

Let a watched folder hand each file to a named intake app, such as filinq's scan intake, through a typed event, and mark the file only when that app accepts it.

• Rows: Woo row 1.7 "Records arrive from a watched folder or a file drop" (not statutory), the intake half, together with parts 1 and 2.
• Wave: 1.
• Depends on: integriq/sources-sftp-adapter-watched-folder ([OpenSpec] sources-sftp-adapter-watched-folder #2550), part 2 of this chain, which depends on integriq/sources-sftp-adapter ([OpenSpec] sources-sftp-adapter #2539).
• Decision: D4 (2026-10-05), integriq owns the folder watcher and filinq's scan intake consumes it.

Build rules: openspec/woo-build-rules.md

Specs

• 📄 data-infra-connectors

Tasks

• Implement
• Test, through the caller: PHPUnit WatchedFileIngestJobTest::testAnAcceptedHandOverMarksTheFile, ::testAnUnclaimedHandOverLeavesTheFile, ::testAnAcceptanceByAnotherAppLeavesTheFile and ::testTheEventCarriesTheFileItFound (the six getters answer the synchronization, source, intake app, file id, path and owner the job found), dispatching the real event class through a real IEventDispatcher. Each fails on development today: the class does not exist.
• Test, the class itself: PHPUnit WatchedFileArrivedEventTest::testTheNamedIntakeMayAccept, ::testAnotherAppIdIsRefused, ::testAnEmptyReferenceIsRefused, ::testASecondAcceptIsRefused, and ::testThePublicSurfaceIsTheContract, which asserts by reflection the constructor parameter names and types, the six getters and their return types and accept(string $appId, string $reference): bool, as literals.
• Cross-app: record in the PR body that filinq's consumer is filinq/scan-intake-from-a-watched-folder ([OpenSpec] scan-intake-from-a-watched-folder filinq#1351), whose WatchedFileArrivedContractTest asserts the same literals on the filinq side and whose listener test dispatches this same class.
• Own clone, git checkout --no-track -b <branch> origin/development, TMPDIR a sibling outside the clone.
• PHPUnit judged by the Tests: line, or with --no-coverage; a green suite exits 1 without a coverage driver.
• run-hydra-gates.sh --base origin/development, counting the gates that ran.
• Once before push: COMPOSER_PROCESS_TIMEOUT=0 composer check:strict, npm run lint, npm run format, npm run check:l10n, npm run check:l10n-js, npm run check:manifest, npm run check:schema-l10n, npm run check:register (the register changed).
• CI runs the gates on the full tree; the coverage guard needs a test for every added statement.
• openspec validate sources-sftp-adapter-intake-hand-over --type change --strict passes.
• One PR, --base development; merge development in, never rebase; no Co-Authored-By trailer.
• Done means merged on development with CI green. Row 1.7 is production only once a store release carries it.

Synced from openspec/changes/sources-sftp-adapter-intake-hand-over by OpenSpec workflow
App: integriq