>From Michael Blow <[email protected]>: Michael Blow has uploaded this change for review. ( https://asterix-gerrit.ics.uci.edu/c/asterixdb/+/21363?usp=email )
Change subject: [NO ISSUE][MISC] += Clarify AiProvenance annotations, CLAUDE.md ...................................................................... [NO ISSUE][MISC] += Clarify AiProvenance annotations, CLAUDE.md Change-Id: I88448bb75c8c4f33c76fa0d7ac2938dfb61fd5be --- A CLAUDE.md M asterixdb/asterix-app/src/test/java/org/apache/asterix/test/common/TestExecutor.java M asterixdb/asterix-cloud/src/test/java/org/apache/asterix/cloud/clients/aws/s3/S3ConnectionLifecycleTest.java M asterixdb/asterix-cloud/src/test/java/org/apache/asterix/cloud/clients/google/gcs/GCSConnectionLifecycleTest.java M hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/NetworkUtil.java M hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/annotations/AiProvenance.java 6 files changed, 72 insertions(+), 6 deletions(-) git pull ssh://asterix-gerrit.ics.uci.edu:29418/asterixdb refs/changes/63/21363/1 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..ede9b86 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,66 @@ +<!-- + ! Licensed to the Apache Software Foundation (ASF) under one + ! or more contributor license agreements. See the NOTICE file + ! distributed with this work for additional information + ! regarding copyright ownership. The ASF licenses this file + ! to you under the Apache License, Version 2.0 (the + ! "License"); you may not use this file except in compliance + ! with the License. You may obtain a copy of the License at + ! + ! http://www.apache.org/licenses/LICENSE-2.0 + ! + ! Unless required by applicable law or agreed to in writing, + ! software distributed under the License is distributed on an + ! "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + ! KIND, either express or implied. See the License for the + ! specific language governing permissions and limitations + ! under the License. + !--> +# AsterixDB + +Apache AsterixDB — the BDMS query engine, storage layer, and Hyracks distributed runtime. See `README.md` for an overview. + +The tree has two roots: +- `asterixdb/` — the AsterixDB engine (SQL++ compiler, external data, cloud, storage). +- `hyracks-fullstack/` — the Hyracks runtime and shared utilities (`hyracks-util`, `hyracks-cloud`, etc.). + +Files here carry the **Apache license header** (see `README.md`). Preserve it when editing or creating files. + +## AI Provenance Annotation + +**When you (an AI agent) generate or assist with Java code in this tree, annotate it with `@AiProvenance`.** This records which model and tool produced the code so the contribution is auditable. The annotation is defined *here*, in this repository. + +- **Annotation**: `org.apache.hyracks.util.annotations.AiProvenance` — source at `hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/annotations/AiProvenance.java`. It is on the classpath of every module that depends on `hyracks-util` (effectively all of them). +- **`@Retention(SOURCE)`** — documentation only; stripped at compile time, so no runtime or bytecode cost. The repeatable container `@AiProvenances` is `RUNTIME`-retained for tools that scan class files. +- **Applies to**: types, methods, constructors, fields, and local variables. + +### Attributes + +| Attribute | Required | Values | +|-----------|----------|--------| +| `agent` | yes | `AiProvenance.Agent` — the model that did the work (e.g. `CLAUDE_OPUS_4_8`, `CLAUDE_SONNET_4_6`, `GPT_5_MINI`) | +| `tool` | yes | `AiProvenance.Tool` — the invocation surface (e.g. `CLAUDE_CODE_UI`, `CLAUDE_CODE_CLI`, `GITHUB_COPILOT`) | +| `contributionKind` | no (default `GENERATED`) | `GENERATED`, `ASSISTED`, `REFACTORED`, `TEST_GENERATED`, `DOC_GENERATED` | +| `notes` | no | free-text, e.g. what changed or why | + +### How to inject it + +1. **Pick the narrowest element** that captures the AI contribution: annotate the **type** only when the **whole class** is AI-authored. When AI adds or rewrites individual **methods** (or a **field**/**constructor**) within an otherwise human-authored class, annotate each of those **methods** — do **not** promote the annotation to the type level. +2. **Match `agent` to the model actually used.** When the author is Claude Code (the Code tab in the Claude app / the `claude` CLI), use `agent = AiProvenance.Agent.CLAUDE_OPUS_4_8` (the current model — update if running a different one) and `tool = AiProvenance.Tool.CLAUDE_CODE_UI`. For the claude.ai chat web app use `CLAUDE_CODE_UI`; for Copilot-in-IDE use `GITHUB_COPILOT`. +3. **Choose `contributionKind`** honestly: `GENERATED` (from scratch), `ASSISTED` (human-led, AI-suggested), `REFACTORED` (rewriting existing code), `TEST_GENERATED`, `DOC_GENERATED`. +4. **Stack annotations** (it is `@Repeatable`) to record history — e.g. generated by one model then refactored by another. +5. **Import style**: either static-import the constants for brevity, or import the type and qualify (`AiProvenance.Agent.X`). Both are used in-tree. + +### Example + +In-tree usages include `asterixdb/asterix-external-data/.../aws/s3/S3Utils.java`, `asterixdb/asterix-cloud/.../S3TrustManagerProvider.java`, and `hyracks-fullstack/hyracks/hyracks-util/.../Span.java`. + +```java +import org.apache.hyracks.util.annotations.AiProvenance; + +@AiProvenance(agent = AiProvenance.Agent.CLAUDE_OPUS_4_8, tool = AiProvenance.Tool.CLAUDE_CODE_UI, + contributionKind = AiProvenance.ContributionKind.GENERATED, notes = "Initial implementation") +public final class ExampleHelper { ... } +``` + +If a model you used is missing from the `Agent`/`Tool`/`Provider` enums, **add it to `AiProvenance.java`** rather than falling back to `OTHER`. diff --git a/asterixdb/asterix-app/src/test/java/org/apache/asterix/test/common/TestExecutor.java b/asterixdb/asterix-app/src/test/java/org/apache/asterix/test/common/TestExecutor.java index 3a77ad2..e3b4b66 100644 --- a/asterixdb/asterix-app/src/test/java/org/apache/asterix/test/common/TestExecutor.java +++ b/asterixdb/asterix-app/src/test/java/org/apache/asterix/test/common/TestExecutor.java @@ -335,7 +335,7 @@ * topology change) must narrow it down to those, otherwise a request can be dispatched to a defined-but-never-started * node. */ - @AiProvenance(agent = AiProvenance.Agent.CLAUDE_OPUS_4_8, tool = AiProvenance.Tool.CLAUDE_UI) + @AiProvenance(agent = AiProvenance.Agent.CLAUDE_OPUS_4_8, tool = AiProvenance.Tool.CLAUDE_CODE_UI) public static void setActiveNcQueryEndPoints(Collection<InetSocketAddress> activeEndPoints) { ncEndPointsList.clear(); ncEndPointsList.addAll(activeEndPoints); diff --git a/asterixdb/asterix-cloud/src/test/java/org/apache/asterix/cloud/clients/aws/s3/S3ConnectionLifecycleTest.java b/asterixdb/asterix-cloud/src/test/java/org/apache/asterix/cloud/clients/aws/s3/S3ConnectionLifecycleTest.java index 3e07a9b..873f59e 100644 --- a/asterixdb/asterix-cloud/src/test/java/org/apache/asterix/cloud/clients/aws/s3/S3ConnectionLifecycleTest.java +++ b/asterixdb/asterix-cloud/src/test/java/org/apache/asterix/cloud/clients/aws/s3/S3ConnectionLifecycleTest.java @@ -66,7 +66,7 @@ * values, drive concurrent uploads to populate the connection pool, then observe established * TCP sockets via {@code lsof} to confirm connections are torn down at the configured times. */ -@AiProvenance(agent = Agent.CLAUDE_OPUS_4_7, tool = Tool.ANTHROPIC_CLI, contributionKind = ContributionKind.TEST_GENERATED, notes = "MB-71767: runtime verification of HTTP idle/lifetime knobs on the sync S3 path; generated via Claude Code") +@AiProvenance(agent = Agent.CLAUDE_OPUS_4_7, tool = Tool.CLAUDE_CODE_CLI, contributionKind = ContributionKind.TEST_GENERATED, notes = "MB-71767: runtime verification of HTTP idle/lifetime knobs on the sync S3 path; generated via Claude Code") public class S3ConnectionLifecycleTest { private static final Logger LOGGER = LogManager.getLogger(); diff --git a/asterixdb/asterix-cloud/src/test/java/org/apache/asterix/cloud/clients/google/gcs/GCSConnectionLifecycleTest.java b/asterixdb/asterix-cloud/src/test/java/org/apache/asterix/cloud/clients/google/gcs/GCSConnectionLifecycleTest.java index e48c4ce..cc5bacf 100644 --- a/asterixdb/asterix-cloud/src/test/java/org/apache/asterix/cloud/clients/google/gcs/GCSConnectionLifecycleTest.java +++ b/asterixdb/asterix-cloud/src/test/java/org/apache/asterix/cloud/clients/google/gcs/GCSConnectionLifecycleTest.java @@ -63,7 +63,7 @@ * * Mirror of {@code S3ConnectionLifecycleTest} for the GCS code path. */ -@AiProvenance(agent = Agent.CLAUDE_OPUS_4_7, tool = Tool.ANTHROPIC_CLI, contributionKind = ContributionKind.TEST_GENERATED, notes = "MB-71767: runtime verification of HTTP idle/lifetime knobs on the GCS path; generated via Claude Code") +@AiProvenance(agent = Agent.CLAUDE_OPUS_4_7, tool = Tool.CLAUDE_CODE_CLI, contributionKind = ContributionKind.TEST_GENERATED, notes = "MB-71767: runtime verification of HTTP idle/lifetime knobs on the GCS path; generated via Claude Code") public class GCSConnectionLifecycleTest { private static final String MOCK_SERVER_REGION = "us-west2"; diff --git a/hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/NetworkUtil.java b/hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/NetworkUtil.java index 592edc2..76d3f65 100644 --- a/hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/NetworkUtil.java +++ b/hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/NetworkUtil.java @@ -235,7 +235,7 @@ return refreshed; } - @AiProvenance(agent = AiProvenance.Agent.CLAUDE_OPUS_4_8, tool = AiProvenance.Tool.CLAUDE_UI, contributionKind = AiProvenance.ContributionKind.REFACTORED) + @AiProvenance(agent = AiProvenance.Agent.CLAUDE_OPUS_4_8, tool = AiProvenance.Tool.CLAUDE_CODE_UI, contributionKind = AiProvenance.ContributionKind.REFACTORED) public static InetSocketAddress toInetSocketAddress(HttpHost httpHost) { // HttpHost.create(String) leaves the resolved InetAddress null; new InetSocketAddress((InetAddress) null, ...) // would yield the wildcard 0.0.0.0, so fall back to resolving the host name in that case. diff --git a/hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/annotations/AiProvenance.java b/hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/annotations/AiProvenance.java index ddd0149..f20956d 100644 --- a/hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/annotations/AiProvenance.java +++ b/hyracks-fullstack/hyracks/hyracks-util/src/main/java/org/apache/hyracks/util/annotations/AiProvenance.java @@ -327,7 +327,7 @@ // Web / Chat UIs CHATGPT_UI(OPENAI, "chatgpt-ui", "ChatGPT"), - CLAUDE_UI(ANTHROPIC, "claude-ui", "Claude (Code) UI"), + CLAUDE_CODE_UI(ANTHROPIC, "claude-code-ui", "Claude Code (Code tab in Claude UI)"), GEMINI_UI(GOOGLE, "gemini-ui", "Gemini UI"), PERPLEXITY(Provider.PERPLEXITY, "perplexity", "Perplexity"), @@ -353,7 +353,7 @@ // CLI tools OPENAI_CLI(OPENAI, "cli", "OpenAI CLI"), - ANTHROPIC_CLI(ANTHROPIC, "cli", "Anthropic CLI"), + CLAUDE_CODE_CLI(ANTHROPIC, "claude-code-cli", "Claude Code CLI"), FACTORY_CLI(Provider.FACTORY, "factory-cli", "Factory.ai CLI"), // Fallback -- To view, visit https://asterix-gerrit.ics.uci.edu/c/asterixdb/+/21363?usp=email To unsubscribe, or for help writing mail filters, visit https://asterix-gerrit.ics.uci.edu/settings?usp=email Gerrit-MessageType: newchange Gerrit-Project: asterixdb Gerrit-Branch: master Gerrit-Change-Id: I88448bb75c8c4f33c76fa0d7ac2938dfb61fd5be Gerrit-Change-Number: 21363 Gerrit-PatchSet: 1 Gerrit-Owner: Michael Blow <[email protected]>
