# ADR-003: Public-read source URL for fetch_oss_file

## Status

Accepted

## Date

2026-07-30

## Context

Controlled SuperAgent traces showed that `fetch_oss_file` accepts `object_uri` and `filename`. An `oss://`
request failed with `public_endpoint_missing`, while earlier HTTPS attempts reached file-type handling. The user
confirmed that the installed Tool reads a publicly accessible OSS address without a Provider and that the OSS
deployment is `public-read`.

The previous ARR adapter explicitly wrote every object with object ACL `private`. That overrides a public-read
bucket and would make a generated public URL unusable. At the same time, making every processing output public
would unnecessarily widen exposure.

## Decision

1. ARR requires the integration bucket to report bucket ACL `public-read`; anonymous writes remain forbidden.
2. Only `committed/source_xml/source.xml` is written with object ACL `public-read`. Staged objects, generated
   reports, result JSON and exchange objects remain explicitly `private`.
3. `arr-opera-daily-program-input-3` includes a required `oss.url` generated by ARR as
   `https://{bucket}.oss-{region}.aliyuncs.com/{encoded-object-key}`. It contains no query signature or secret.
4. The Main Prompt passes `oss.url` unchanged as `fetch_oss_file.object_uri` and the canonical attachment name
   as `filename`, exactly once. It must not construct `oss://`, sign or substitute another URL.
5. XML extension/MIME acceptance remains a separate platform Tool configuration requirement.

## Rationale

ARR owns the bucket, endpoint and immutable object key, so it can generate one deterministic address without
asking the Agent to infer storage semantics. Object-level ACL selection satisfies anonymous source download
while keeping intermediate and output artifacts private.

## Consequences

- `fetch_oss_file` needs no OSS Provider, AccessKey or signed URL for this flow.
- A committed source XML is anonymously readable to anyone who has its URL; the URL is not a secret or an
  authorization mechanism. Retention, access logging and public-source privacy review remain deployment duties.
- Readiness now rejects a private bucket for this integration.
- Deploying code and Prompt changes does not by itself allow XML; the platform must permit `.xml` and
  `application/xml` if it still returns `extension_not_allowed`.

## Supersedes

- The private-object/credential-backed Provider assumption in earlier implementation notes and the historical
  `oss://` Prompt experiment.

## Related

- `arr_processing/source_message.py`
- `arr_storage/aliyun_oss_v2.py`
- `prompts/arr_opera_daily_program_input.schema.json`
- `prompts/arr_opera_daily_main_agent_prompt.md`
- `.project-docs/50-evidence/topics/2026-07-30-superagent-fetch-oss-prompt-experiment.md`
