# TASK 0: Freeze Framework Boundary, Adapter Ownership, And Brink Migration Target

## Summary

Freeze the implementation boundary for the ETL framework extraction before code movement starts.

## Implementation Status

Status: implemented.

Verified in code and docs:

- framework vs adapter ownership is explicitly documented in `specs/EtlSourceAdapterFramework/TASK.md` and `docs/features/ETL/etl-source-adapter-framework.md`,
- the implemented runtime follows that split through `backend/Kds.Ai.Integrations/Etl/*` and `backend/Kds.Ai.Integrations/BrinkPos/*`,
- the Brink migration target remains the active four-stage `Sales2.GetOrders` path only.

This task prevents three kinds of drift:

- turning the slice into a full ETL redesign,
- over-abstracting source-specific behavior,
- migrating Brink in a way that broadens runtime scope instead of only changing ownership boundaries.

## Dependencies

- none

## Files to Modify

- `specs/EtlSourceAdapterFramework/TASK.md`
- `specs/EtlSourceAdapterFramework/TASK0.md`
- optionally `docs/features/ETL/etl-source-adapter-framework.md` if terminology is tightened

## Required Decisions

### 1. Freeze framework-owned responsibilities

Document that the framework owns:

- pipeline orchestration,
- stage lifecycle and upstream batch handling,
- checkpoint advancement policy,
- failure package writing contract,
- warehouse transaction execution helpers,
- common diagnostics envelopes.

### 2. Freeze adapter-owned responsibilities

Document that source adapters own:

- credentials and source connection semantics,
- transport clients and endpoint calling logic,
- business date rules,
- parser internals,
- source contract definitions,
- staging table definitions,
- curated mapping rules and SQL.

### 3. Freeze the first migration target

Document that the first source migrated to the framework is the currently active Brink POS ETL path only.

The active Brink migration target is limited to:

- `extract_raw`,
- `normalize_load`,
- `load_to_staging`,
- `staging_to_curated`,
- the current `Sales2.GetOrders` active path.

### 4. Freeze the non-goals

Document that this slice must not:

- add new source systems,
- broaden Brink runtime scope,
- redesign warehouse foundation,
- redesign replay architecture,
- force one extraction model across all source types.

## Acceptance Criteria

- framework-owned responsibilities are explicitly listed,
- adapter-owned responsibilities are explicitly listed,
- Brink migration target is explicitly limited to the active current path,
- non-goals clearly prevent architecture sprawl.

## Proposed Boundary Matrix

| Concern | Framework | Adapter |
|---|---|---|
| Stage sequencing | Owns | Uses |
| Batch start/complete/fail | Owns | Uses |
| Upstream batch resolution | Owns | Uses |
| Checkpoint policy | Owns | Supplies stage identity only |
| Failed package shape | Owns | Supplies source/stage context |
| Tenant warehouse resolution | Owns | Uses |
| Warehouse transaction helper | Owns | Uses |
| Source credentials | Does not own | Owns |
| External API client | Does not own | Owns |
| Business date semantics | Does not own | Owns |
| Parser logic | Does not own | Owns |
| Normalization profile implementation | Does not own | Owns |
| Staging table definitions | Contract shape only | Owns content |
| Curated target definitions | Contract shape only | Owns content |

## Canonical Terms For Later Tasks

- `framework runtime` means orchestration and shared ETL mechanics.
- `source adapter` means one source-specific package registered into the framework.
- `stage` means one pipeline step such as `extract_raw` or `load_to_staging`.
- `catalog` means adapter-owned metadata collection exposed through a shared contract.
- `descriptor` means the shared source identity object used by the framework.

## Proposed Implementation Shape

The later tasks should assume the following ownership baseline:

1. framework code may know that a source has stages and catalogs,
2. framework code may not know Brink SOAP, XML shape, or Brink-specific SQL,
3. adapter code may call shared services, but should not re-implement lifecycle, checkpoint, or failure mechanics,
4. the first migration path should wrap current Brink jobs behind shared contracts before attempting deeper internal rewrites.

## Decision Record

### Framework owns mechanics

The framework owns repeatable ETL mechanics that are already shared in behavior across stages and sources, including pipeline execution, stage lifecycle, checkpoint policy, failure packaging, warehouse execution helpers, and common diagnostics envelopes.

### Adapter owns source knowledge

Source adapters own source-specific knowledge, including credentials, transport, business-date semantics, parser logic, source contracts, staging definitions, and curated mapping rules.

### Brink is the first migration baseline

The first framework migration target is the current active Brink POS ETL path only. The extraction must prove that the framework works for real code without using the slice to broaden runtime scope.

### This slice is an extraction, not a redesign

The purpose of this work is to extract a reusable internal framework from an existing implementation. It must not become a platform rewrite or speculative multi-source redesign.