# Add sources and ingest events

Supported inputs, importing native records and what connection status means.

Contract: console-v1. Stage: private evaluation. Source snapshot: 23fdccfaa88f69e858769f1dad70f82739e2740f.

## Supported native shapes—not blanket connectors

The implemented source kinds are aws_cloudtrail (CreateAccessKey with required access-key response evidence only), google_workspace (login failure/success and Drive download, one activity per native record), and cloudwatch_sample_service (synthetic auth.login denied, numeric schema_version:1, no actor/sensitive audit payload). Other CloudTrail event types and arbitrary Workspace admin events are not implied. GCP Cloud Logging, Azure Activity Log and other provider families remain planned. All current mappings are partial.

## Minimal onboarding sequence

Choose the source kind; preview exact permissions, allowed account/customer identity, selected Region, data and storage scope; configure a manual import or attach-existing worker; run preflight; send an approved canary; inspect native evidence and operation lane receipts; then inspect source health. Saving a source does not make it connected. Canary evidence is not verification of provider credentials. OAuth self-service and automatic resource provisioning are not complete.

## Transport configuration

Allowed config keys are transport, log_groups, queue_url, application and non-secret credential_reference. Supported transports are manual, aws_sqs_cloudtrail, aws_cloudwatch and google_workspace, with a matching kind. CloudWatch requires an explicit 1–10 log-group allowlist (each at most 512 bytes), including manual sample imports; SQS requires queue_url. Workspace application is login, drive or admin, but choosing admin does not add unsupported mappings. Keep provider credentials in the separately scoped acquisition worker, never a source API payload.

## Read preflight literally

POST /api/v1/sources/{id}/preflight with JSON headers and {}. Manual sources can report ready_for_import. Provider paths report external_worker_required with provider_verified:false. A validated canary can report canary_received; list status may become receiving when retained events exist. None of these are a claim that the API performed live provider identity checks.

## Ingest with a scoped source token

NATIVE_BATCH_FILE must contain approved native records under records (CloudTrail Records is also accepted), not a generic invented event. SOURCE_ID is the UUID returned at source creation. SOURCE_TOKEN is the secret issued once by the operator. Do not log the Authorization header. Maximum 1,000 records and 8 MiB request. The endpoint retains exact request bytes plus record ordinal/provenance.

```sh
curl --fail-with-body --silent --show-error \
  "$CONSOLE_URL/api/v1/sources/$SOURCE_ID/ingest" \
  -H "Authorization: Bearer $SOURCE_TOKEN" \
  -H "Content-Type: application/json" --data-binary "@$NATIVE_BATCH_FILE"
```

## 202 is not source acknowledgement

The accepted response records durable PostgreSQL inbox/receipt state and accepted/replayed/quarantined counts. Poll GET /api/v1/operations/{operation_id} with the same token until status is committed. Inspect hot/archive/stream lane receipts. Do not advance a durable cursor or acknowledge SQS on HTTP 202. Pending, failed or outcome-unknown dependencies are not permission to acknowledge. Invalid records need durable raw-batch/quarantine disposition.

```sh
curl --fail-with-body --silent --show-error \
  "$CONSOLE_URL/api/v1/operations/$OPERATION_ID" \
  -H "Authorization: Bearer $SOURCE_TOKEN"
```

## Replay and retained limits

Deduplication binds tenant/source/native key and content digest. Identical native replay does not duplicate alert, case, workflow or audit effects; changed content under the same key is conflict/quarantine, not overwrite. Replayed requests still consume raw-batch/retained-byte capacity. Each evaluation tenant is capped at 10,000 unique normalized events, 10,000 raw batches and 256 MiB retained request bytes. These are safety limits, not retention or throughput promises.