# Migration and compatibility

Start with the S3-compatible surface when replacing an endpoint in an existing application. Move selected workflows to
the native client only when JSON errors, constrained signed URLs, browser CORS, notifications, or the app kit materially
simplify the application.

## S3 migration checklist

1. Pin a Lockwell server release and the matching first-party SDK release line.
2. Use path-style addressing first; enable virtual-hosted style only after wildcard DNS/TLS validation.
3. Set the region explicitly when it differs from `us-east-1`.
4. Run the application's real object names, ranges, checksums, multipart sizes, versioning, and Object Lock denial
   paths.
5. Replace provider-specific IAM/STS/KMS/event-bus features instead of assuming S3 wire compatibility includes them.
6. Verify backup/restore and migration-copy evidence before making a provider-replacement claim.

Lockwell supports the operations in the [S3 operations reference](/reference/s3-operations). Unsupported subresources
fail closed. The compatibility matrix is evidence, not permission to infer an unlisted feature.

## Native adoption

Native clients use `/api/v1/` on the public object listener and auto-manage short-lived bearer tokens minted from an
access key. Admin clients use `/admin/api/v1/` on the private admin listener and an admin token. Do not swap their
credentials or expose the admin listener as a public object endpoint.

The app kit composes existing native/admin calls; it does not introduce a fourth wire API. Keep application-owned tenant
and ERP mappings in the application database, and use opaque identifiers rather than customer names or tax ids.

### Selecting Native Wire during migration

LNW/1 is an explicit, experimental binary transport for the native data plane. It runs on a separate configured TLS 1.3
listener and has no JSON/S3 fallback. Migrate a server-side workflow only after the target runtime appears in the
[Native Wire capability index](/reference/sdk-capabilities): the currently merged consumers are the Node/Bun shared
TypeScript client, SolidStart v2 server adapter, and Spring Boot starter. Keep S3 or HTTP-native JSON as an explicitly
selected rollback mode, and do not catch a native error to silently change transports. There is no transparent byte-offset
resume; use idempotency keys or committed multipart parts.

## Supported native SDK languages

The currently supported first-party SDK languages are Go, Node/TypeScript, and Java. There is no first-party .NET,
Rust, PHP, or Ruby SDK; those languages are explicit product non-goals. Applications in those ecosystems may use a
compatible S3
library against the documented S3 surface, but that does not create a native/admin SDK support claim.

Proposal documents, generated OpenAPI experiments, and unexported server handlers are not public SDK APIs. A capability
is documented here only when exported source and executable tests support it.

## Security differences to preserve

- Buckets remain private; there is no anonymous/public-bucket migration mode.
- S3 presigned GET/PUT/HEAD/DELETE and native signed GET/PUT URLs are bearer capabilities. Keep TTLs short.
- SSE-C is supported on the S3 surface with typed helpers; SSE-KMS is not.
- Retention and legal-hold denials are expected safety behavior, not compatibility bugs.
- Never log access-key secrets, admin/bearer tokens, SSE-C keys, raw object data, or signed URL query strings.

## Release and package boundary

Examples use historical `0.2.2` coordinates. Lockwell is closed source during early access: current packages and a
licence come with access ([hello@rusticstack.com](mailto:hello@rusticstack.com)). Do not infer public package publication from documentation
alone.