Spensara Spensara Knowledge Base & Documentation Repository
System Overview Brink & Borg Master Index (722 Docs) Spensara Platform Project Tracker

Repository Docs & Knowledge Base

Consolidated Spensara documentation repository (722 Markdown & architecture documents in ../repository)
Built Word Documents (.docx): Spensara Overview (.docx) Capability Assessment (.docx) Brink POS Ingestion Analysis (.docx) The Borg Ingestion Architecture (.docx)

Categories

Implementation Specs (157)

Detailed engineering and feature implementation specifications.
implementation-specs/specs/EtlSourceAdapterFramework/TASK0.md 5,301 bytes · Updated Oct 23, 2026 10:44 AM EDT
Raw File

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

ConcernFrameworkAdapter
Stage sequencingOwnsUses
Batch start/complete/failOwnsUses
Upstream batch resolutionOwnsUses
Checkpoint policyOwnsSupplies stage identity only
Failed package shapeOwnsSupplies source/stage context
Tenant warehouse resolutionOwnsUses
Warehouse transaction helperOwnsUses
Source credentialsDoes not ownOwns
External API clientDoes not ownOwns
Business date semanticsDoes not ownOwns
Parser logicDoes not ownOwns
Normalization profile implementationDoes not ownOwns
Staging table definitionsContract shape onlyOwns content
Curated target definitionsContract shape onlyOwns 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.