# Context owned object storage

Tracking: [TypeScript #53](https://github.com/teaql/teaql-ts/issues/53),
[shared contract #122](https://github.com/teaql/teaql-conformance/issues/122).

Core exports contain portable typed values and asynchronous byte-stream contracts.
The optional server-only `@teaql/teaql/object-storage/s3` entry requires the pinned
`@aws-sdk/client-s3` and `@aws-sdk/s3-request-presigner` peers (3.1151.0), Node 20+,
and filesystem access. It is not imported by the browser core entry point.
SDK credentials, endpoints and buckets are configured at trusted startup.

```typescript
import {UserContext,ObjectKey,ObjectPutOptions} from '@teaql/teaql';
import {S3ObjectStorage} from '@teaql/teaql/object-storage/s3';

const provider = new S3ObjectStorage(sdkClient, 'attachments');
const storage = new UserContext().withObjectStorage(provider)
  .objectStorage('store payment receipt attachment');
const key = new ObjectKey('receipts/opaque-reference.pdf');
await storage.put(key, source, new ObjectPutOptions(contentLength, 'create_only'));
const link = await storage.getReadUrl(key);
// Return link.url to an authorized caller; never log it.
const response = await storage.get(key);
try { for await (const block of response.stream) { /* consume bytes */ } }
finally { await response.close(); }
```

Upload iterators are finalized on every exit. The adapter stages to a private
temporary file with bounded buffers and exact length checks, capped at 5 GiB.
It reopens the staged body for at most three transport/service retry attempts;
conditional PUT remains atomic. Downloads stream and must be consumed or closed.
`getBytes(key, maximumBytes)` requires an explicit memory ceiling. Replacement
is explicit; permissions and outages never become false absence.

Keys are durable; five-minute read URLs are reusable bearer links and can expire
early with credentials/policy. Issuing a URL does not check existence or grant
domain permission. Core inspection/diagnostic events exclude keys, metadata,
body, credentials, URLs and SDK messages. The observer/telemetry resource is
installed on Context (`objectStorageObserver` / `runtimeTelemetry`). S3 writes
remain independent of SQL transactions.

After installing this checkout's dependencies, set `TEAQL_S3_ENDPOINT`,
`TEAQL_S3_BUCKET`, `TEAQL_S3_ACCESS_KEY`, `TEAQL_S3_SECRET_KEY` to a dedicated
test service and run `bash examples/object-storage/verify.sh` twice. The example
uses a fresh local build, creates its fixture bucket if missing and removes
only its unique keys. The production provider never creates buckets. The gate
qualifies the dedicated fixture; other compatible services require their own
tests. Multipart, list/copy/range, signed upload and browser credentials are
outside this first server adapter.