OCI authentication-provider constructors.

Each public fn returns an `AbstractAuthenticationDetailsProvider` — the
marker interface that every OCI client's `Builder.build(...)` accepts.
Pass the result to `clj-oci.clients/build-*-client` for a one-shot
client, or to the 2-arity `clj-oci.clients/*-client-for-region` /
`:auth-details`-keyed `clj-oci.clients/*-client-for` for the per-region
cache.

No auto-detection. No implicit env-var consultation. No silent fallback.
The caller picks the provider by name. The existing `~/.oci/config`
path is what `clj-oci.clients/authentication-details` provides
(singleton); everything in this namespace is the explicit alternative
for OCI-native runtimes (Instance Principal, Resource Principal, OKE
workload identity, workload-identity federation, session token) and for
tests.

Why the unusual return type: `InstancePrincipalsAuthenticationDetailsProvider`
and `ResourcePrincipalAuthenticationDetailsProvider` do NOT implement
`AuthenticationDetailsProvider` (only `AbstractAuthenticationDetailsProvider`,
the marker interface). So we declare the marker — which is also what
every client builder's `.build` actually accepts.

Javadocs: https://docs.oracle.com/en-us/iaas/tools/java/3.86.0/

OCI Compute API wrapper — Instance CRUD + lifecycle.

Provides operations for the canonical `Instance` resource on `ComputeClient`:
- `list-instances`             — paginated listing with filters
- `get-instance`               — fetch a single instance
- `launch-instance`            — create
- `update-instance`            — update mutable fields
- `terminate-instance`         — delete
- `instance-action`            — power state (START/STOP/RESET/SOFTSTOP/...)
- `change-instance-compartment`— move between compartments

Plus helpers for the most common polymorphic launch-input slot:
- `image-source-details`       — InstanceSourceViaImageDetails
- `boot-volume-source-details` — InstanceSourceViaBootVolumeDetails

`list-instances` results are cached via `service.memo`; mutations bypass the
cache and invalidate the `compute/list-instances` prefix on success.

Note: `oci/http-request` currently discards response headers, so this
namespace cannot return `etag` for optimistic concurrency or
`opc-work-request-id` for async tracking. Wrappers accept `:if-match`
outbound but cannot surface header values inbound.

OCI FileStorage API wrapper.

Provides paginated filesystem listing via `list-file-systems`. Requires
both `compartment-id` and `availability-domain` — unlike Compute, the
FileStorage API mandates an AD per request.

Uses `clojure.java.data.builder/to-java` with `:limit` pre-coerced to
`Integer` to satisfy the SDK setter type under cloverage instrumentation.

Results are cached via `service.memo` keyed by compartment-id and
availability-domain — subsequent calls with the same params return
cached data unless `:refresh?` is set.

OCI Generative AI Service Management API wrapper — Models + Imported Models.

Provides full CRUD + list + compartment-move on the two control-plane
resource types of the Generative AI service:

- **Model** (BASE pretrained or CUSTOM fine-tuned):
  `list-models`, `get-model`, `create-model`, `update-model`,
  `change-model-compartment`, `delete-model`.

- **ImportedModel** (externally sourced from Object Storage or Hugging Face):
  `list-imported-models`, `get-imported-model`, `create-imported-model`,
  `update-imported-model`, `change-imported-model-compartment`,
  `delete-imported-model`.

Plus helpers for the polymorphic input slots; the OCI SDK exposes these as
abstract base classes with multiple concrete subclasses, and `oci-build`
does not auto-dispatch on JSON discriminators. Callers compose pre-built
Java instances via the helpers below and pass them through:

- `object-storage-dataset`     — `Dataset` → `ObjectStorageDataset`
- `t-few-training-config`      — `TrainingConfig` → `TFewTrainingConfig`
- `vanilla-training-config`    — `TrainingConfig` → `VanillaTrainingConfig`
- `lora-training-config`       — `TrainingConfig` → `LoraTrainingConfig`
- `object-storage-data-source` — `ModelDataSource` → `ObjectStorageObject`
- `hugging-face-data-source`   — `ModelDataSource` → `HuggingFaceModel`
- `fine-tune-details`          — composes a dataset + cluster + config

The service is regional (12 endpoint regions). Operations route via
`clients/generativeai-client-for`, which resolves the region from
`(:region opts)` > the resource OCID's region segment > the singleton
default — same precedence as Compute and FileStorage.

Async operations (`create-model`, `delete-model`, `create-imported-model`,
`update-imported-model`, `delete-imported-model`) return an `:opcWorkRequestId`
in `:data`. The Generative AI work-request polling API
(`GetWorkRequest`/`ListWorkRequests`/etc.) is not wrapped in this slice;
callers query externally if they need to wait.

Note: `oci/http-request` discards response headers, so this namespace
accepts `:if-match` outbound but cannot surface `etag` or `opc-request-id`
inbound — same limitation as `compute.clj`.

OCI Generative AI Agents Service Management API wrapper.

This slice (clj-oci 1.8.3) exposes only `list-agents`. The Generative AI
Agents service has 44 operations across 8 resource types (Agents,
AgentEndpoints, KnowledgeBases, DataSources, DataIngestionJobs, Tools,
ProvisionedCapacity, WorkRequests); broader coverage is a separate slice.

Distinct from `clj-oci.generative-ai`, which wraps `oci-java-sdk-generativeai`
(Model + ImportedModel CRUD). This namespace wraps
`oci-java-sdk-generativeaiagent` — different service, different SDK artifact,
different client class.

The service is regional. Operations route via
`clients/generativeai-agent-client-for`, with the same precedence as Compute
and Generative AI Models: (:region opts) > OCID region segment > the
singleton's default.

OCI Identity API wrapper.

Provides paginated compartment listing via `list-compartments` and
non-paginated availability domain listing via `list-availability-domains`.
Uses `clojure.java.data.builder/to-java` with `:limit` pre-coerced to
`Integer` and `:accessLevel` passed as the Java enum constant directly
to satisfy SDK setter types under cloverage instrumentation.

Results are cached via `service.memo` — subsequent calls with the same
tenancy-id return cached data unless `:refresh?` is set.

OCI Instance Maintenance API wrapper.

Provides operations for managing instance maintenance events:
- `list-maintenance-events` — paginated listing with filters
- `get-maintenance-event` — single event by OCID
- `update-maintenance-event` — reschedule or modify an event
- `get-maintenance-reboot` — max reschedule date for an instance

Uses `ComputeClient` via `clj-oci.clients`. No caching — maintenance
events are dynamic (state transitions) and always fetched fresh.

OCI Organizations API — DomainGovernance resource (Tenant Manager Control Plane).

A DomainGovernance is the governance/ONS-notification configuration
attached to a claimed Domain. Five ops served by `DomainGovernanceClient`,
all synchronous:

- `create-domain-governance` — attach governance to a claimed Domain (200, returns DG)
- `get-domain-governance`    — fetch one DomainGovernance
- `list-domain-governances`  — list in a compartment (paginated, filterable)
- `update-domain-governance` — update subscription email / governance flag / tags (200)
- `delete-domain-governance` — remove governance from a Domain (204, no body)

`list-domain-governances` filters by `domainId`, `domainGovernanceId`,
`lifecycleState` (shared 6-state enum), and `name`, plus standard
`sortBy`/`sortOrder`/`limit`/`page`.

Region routing follows the standard pattern.

OCI Organizations API — Domain resource (Tenant Manager Control Plane).

A Domain represents a domain name registration claimed by a tenancy and
verified via a DNS TXT record. Five ops served by `DomainClient`:

- `create-domain` — begin domain registration (201 + Domain body + workReqId)
- `get-domain`    — fetch a Domain
- `list-domains`  — list Domains in a compartment (paginated, filterable)
- `update-domain` — update tags only (sync; SDK does not surface other mutables)
- `delete-domain` — release the domain (async; the SDK omits the
                    `opc-work-request-id` header on this op, so the wrapper
                    returns `{:data {}}` on acceptance)

`list-domains` filters by `domainId`, `lifecycleState`, `status`, `name`,
plus standard `sortBy`/`sortOrder`/`limit`/`page`. Note the `lifecycleState`
filter uses the *shared* `LifecycleState` enum (6 values) even though the
`Domain` model only ever populates 3 (`Active`/`Deleted`/`Failed`).

Region routing follows the standard pattern.

OCI Organizations API — Governance ops (Tenant Manager Control Plane).

Two opt-in/opt-out actions on an organization's child tenancy, served by
the dedicated `GovernanceClient`:

- `add-governance`    — opt the tenancy in to organization governance rules
- `remove-governance` — opt the tenancy out of organization governance rules

Both are async (202 + `opcWorkRequestId`) and take no body. Path shape is
`/organizations/{organizationId}/tenancies/{organizationTenancyId}/actions/<add|remove>Governance`.

Region routing follows the rest of the Organizations namespace tree —
`(:region opts)` > organization OCID's region segment > singleton default.

OCI Organizations API — Link resource (Tenant Manager Control Plane).

A Link is the parent↔child tenancy relationship inside an organization.
Three ops served by `LinkClient`:

- `get-link`     — fetch one Link
- `list-links`   — list links (paginated, filterable)
- `delete-link`  — start the link termination workflow (async, returns workReqId)

`list-links` filters by parent tenancy, child tenancy, lifecycle state, and
sort order (no `sort-by` on this op).

Region routing follows the standard pattern: `(:region opts)` >
link OCID's region segment > singleton default.

OCI Organizations API — Organization resource (Tenant Manager Control Plane).

Three control-plane ops on the Organization resource itself:

- `get-organization`    — fetch one Organization by OCID
- `list-organizations`  — list Organizations in a compartment (paginated)
- `update-organization` — set `defaultUcmSubscriptionId` (async, returns workReqId)

The Organizations service is regional (43 endpoints). All ops route via
`clients/organization-client-for`, which resolves the region from
`(:region opts)` > the organization OCID's region segment > the singleton
default. ListOrganizations takes a compartment OCID (no region segment) so
it falls back to `:region` opt or the singleton.

Note: `oci/http-request` discards response headers, so this namespace
accepts `:if-match` outbound but cannot surface `etag` or `opc-request-id`
inbound — same limitation as `compute.clj` and `generative_ai.clj`.

OCI Organizations API — OrganizationTenancy resource (Tenant Manager Control Plane).

Six ops on tenancies that belong to an organization, all served by
`OrganizationClient`:

- `list-organization-tenancies`         — list children of an organization (paginated)
- `get-organization-tenancy`            — fetch one OrganizationTenancy
- `approve-organization-tenancy-for-transfer`   — approve a child for transfer (sync, returns OT)
- `unapprove-organization-tenancy-for-transfer` — cancel a transfer approval (sync, returns OT)
- `delete-organization-tenancy`         — start tenancy termination (async, returns workReqId)
- `restore-organization-tenancy`        — restore a deleted tenancy (async, returns workReqId)

Region resolution mirrors the rest of the Organizations namespace tree:
`(:region opts)` > OCID-derived > singleton default.

Note the path-param naming asymmetry across ops: `get-organization-tenancy`
uses `tenancyId` while sibling action ops use `organizationTenancyId` for
what is effectively the same OCID. The wrapper accepts a single
`organization-tenancy-id` string and routes it to whichever Java field the
SDK method actually requires.

Async ops surface `:opcWorkRequestId` in `:data`; the work-request polling
API is not wrapped in this slice.

OCI Region API wrapper.

- `list-regions` — all available OCI regions (global, no params)
- `list-region-subscriptions` — regions subscribed by a tenancy
- `create-region-subscription` — subscribe a tenancy to a new region

Uses `IdentityClient` via `clj-oci.clients`. No caching — region data
is static and calls are infrequent.

Builds OCI Java SDK request objects from nested Clojure maps.

`oci-build` is the public entry point. It accepts a target Java class,
the corresponding schema from `oci-doc`, a Clojure params map, and an
enum registry from `enum-registry`. It is intended to be called from
`clj-oci.oci/oci-request`.

Error reporting uses breadcrumb paths so failures are easy to locate:

  (oci-build RequestSummarizedUsagesRequest
             request-schema
             {:requestSummarizedUsagesDetails
              {:granularity :typo ...}}
             enum-reg)
  ;; => throws ex-info with:
  ;;    {:path     [:requestSummarizedUsagesDetails :granularity]
  ;;     :expected {:type ...Granularity :enum-values [Hourly Daily ...]}
  ;;     :got      :typo}

OCI Vault Secret Retrieval API — read decrypted secret bundles.

This namespace wraps the `SecretsClient` SDK class (Maven artifact
`oci-java-sdk-secrets`). The Retrieval API endpoint is
`secrets.vaults.<region>.oci.oraclecloud.com` (path version `/20190301`).
Distinct from `clj-oci.vault.secrets`, which wraps the Management API
(`vaults.<region>...`, path `/20180608`).

Operations:
  get-secret-bundle, get-secret-bundle-by-name, list-secret-bundle-versions.

The two get-* ops are the primary entry points for an application that
needs to read a secret at runtime (e.g. pull a DB password on startup).
Selectors `:version-number` / `:secret-version-name` / `:stage` are
mutually exclusive at the server; default returns the `CURRENT` version.

Service is regional. Routes via `clients/secrets-client-for`.

Javadocs: https://docs.oracle.com/en-us/iaas/tools/java/3.86.0/

OCI Bulk Tag and Standard Tag Template API wrapper.

Provides operations for bulk tag management and standard templates:
- `bulk-delete-tags` — delete multiple tag definitions (async)
- `bulk-edit-tags` — add/update/remove tags on resources (async)
- `list-bulk-edit-tags-resource-types` — metadata: which resource types support bulk edit
- `import-standard-tags` — import Oracle standard tag templates (async)
- `list-standard-tag-namespaces` — list available standard templates
- `get-standard-tag-template` — get a specific standard template

Uses `IdentityClient` via `clj-oci.clients`. No caching — tags are
dynamic and always fetched fresh.

Shared helpers for OCI Tag API modules.

Lock detail builders and enum maps used by `clj-oci.tag.namespaces`
and `clj-oci.tag.defaults`.

OCI Tag Default API wrapper.

Provides operations for managing tag defaults:
- `list-tag-defaults` — paginated listing with filters
- `assemble-effective-tag-set` — resolved defaults for a compartment hierarchy
- `get-tag-default` — single default by OCID
- `create-tag-default` — create a new default
- `update-tag-default` — update value or required flag
- `delete-tag-default` — delete a default
- `add-tag-default-lock` / `remove-tag-default-lock` — resource locking

Uses `IdentityClient` via `clj-oci.clients`. No caching — tag defaults
are dynamic and always fetched fresh.

OCI Tag Definition API wrapper.

Provides operations for managing tag definitions within namespaces:
- `list-tags` — paginated listing within a namespace
- `list-cost-tracking-tags` — paginated listing of cost-tracking tags
- `get-tag` — single tag by namespace OCID + name
- `create-tag` — create a new tag definition
- `update-tag` — update description, retire, cost-tracking, validator
- `delete-tag` — delete a tag definition (async, must retire first)

Uses `IdentityClient` via `clj-oci.clients`. No caching — tags are
dynamic and always fetched fresh.

OCI Tag Namespace API wrapper.

Provides operations for managing tag namespaces:
- `list-tag-namespaces` — paginated listing with filters
- `get-tag-namespace` — single namespace by OCID
- `create-tag-namespace` — create a new namespace
- `update-tag-namespace` — update description, retire/reactivate
- `delete-tag-namespace` — delete an empty namespace
- `cascade-delete-tag-namespace` — delete namespace and all its tags (async)
- `change-tag-namespace-compartment` — move namespace between compartments
- `add-tag-namespace-lock` / `remove-tag-namespace-lock` — resource locking

Uses `IdentityClient` via `clj-oci.clients`. No caching — tags are
dynamic and always fetched fresh.

OCI Tagging Work Request API wrapper.

Provides operations for tracking async tagging operations:
- `get-tagging-work-request` — single work request by OCID
- `list-tagging-work-requests` — paginated listing by compartment
- `list-tagging-work-request-errors` — paginated errors for a work request
- `list-tagging-work-request-logs` — paginated logs for a work request

Uses `IdentityClient` via `clj-oci.clients`. No caching — work requests
are dynamic and always fetched fresh.

Tenancy resource wrappers + env-var helper.

SDK ops here use `IdentityClient` — region-routed via
`clj-oci.clients/identity-client-for`. For tenancies whose home region
differs from the auth provider's default, supply `:region` in `opts`.

OCI Usage API built on `oci-build`.

Where `clj-oci.usageapi` hand-rolls builders for each SDK type, this namespace
uses the introspected schema (`oci-doc`) and `oci-build` to construct request
objects from plain Clojure maps.  Enum keywords, nested builders, and
List<T> elements are all handled automatically.

OCI Vault Secret Management API — Secret resource (9 operations).

This namespace wraps the `VaultsClient` SDK class (Maven artifact
`oci-java-sdk-vault`). The Vault Management API endpoint is
`vaults.<region>.oci.oraclecloud.com` (path version `/20180608`); it is
distinct from the Vault Retrieval API (`secrets.vaults.<region>...`,
wrapped by `clj-oci.secrets`).

Operations:
  list-secrets, get-secret, create-secret, update-secret,
  schedule-secret-deletion, cancel-secret-deletion,
  change-secret-compartment, rotate-secret, cancel-secret-rotation.

Polymorphic body fields (`secretContent`, `secretGenerationContext`,
`secretRules`, `rotationConfig`) are constructed via per-subclass helpers
in `clj-oci.vault.types`, then passed pre-built through the params map.

The service is regional. Operations route via
`clients/vaults-client-for-region` with the usual precedence:
(:region opts) > OCID region segment > singleton's default.

Javadocs: https://docs.oracle.com/en-us/iaas/tools/java/3.86.0/

Polymorphic builders + supporting enum maps for the OCI Vault Secret
Management API.

This module is the shared foundation for `clj-oci.vault.secrets` and
`clj-oci.vault.versions`. It does NOT make SDK calls — it produces Java
model instances that those modules pass into `builder/to-java` when
constructing request bodies.

The Vault SDK has four polymorphic base classes with Jackson-style
discriminators, plus one non-polymorphic composer (`RotationConfig`)
that contains a polymorphic field:

  SecretContentDetails    — Base64SecretContentDetails
  SecretGenerationContext — Bytes / Passphrase / SshKey GenerationContext
  SecretRule              — SecretExpiryRule, SecretReuseRule
  TargetSystemDetails     — Adb / Function TargetSystemDetails
  RotationConfig          — contains TargetSystemDetails

Per the clj-oci convention (see CLAUDE.md), `oci-build` does NOT
auto-dispatch on a discriminator key. Each concrete subclass has its own
tiny helper that wraps `builder/to-java` for that concrete builder; the
downstream composer (`create-secret`, `update-secret`) accepts the pre-built
Java instance and assembles the request.

Javadocs: https://docs.oracle.com/en-us/iaas/tools/java/3.86.0/

OCI Vault Secret Management API — SecretVersion sub-resource (4 operations).

This namespace wraps the SecretVersion ops on `VaultsClient`. Sub-resource
of Secret (path: `/secrets/{secretId}/version/{versionNumber}`); operations
work against a specific version of an existing secret.

Operations:
  get-secret-version, list-secret-versions,
  schedule-secret-version-deletion, cancel-secret-version-deletion.

Region-aware via `clients/vaults-client-for`. Same precedence as
`vault.secrets`.

Javadocs: https://docs.oracle.com/en-us/iaas/tools/java/3.86.0/