8 files changed, 38 insertions, 2 deletions
diff --git a/ext/jni/GNUmakefile b/ext/jni/GNUmakefile
index 05f05679c..cd5150eb1 100644
--- a/ext/jni/GNUmakefile
+++ b/ext/jni/GNUmakefile
@@ -59,6 +59,7 @@ $(bin.version-info): $(dir.tool)/version-info.c $(sqlite3.h) $(dir.top)/Makefile
 # Be explicit about which Java files to compile so that we can work on
 # in-progress files without requiring them to be in a compilable statae.
 JAVA_FILES.main := $(patsubst %,$(dir.src.jni)/%,\
+  annotation/Canonical.java \
   annotation/NotNull.java \
   annotation/Nullable.java \
   AggregateFunction.java \
diff --git a/ext/jni/src/org/sqlite/jni/AuthorizerCallback.java b/ext/jni/src/org/sqlite/jni/AuthorizerCallback.java
index 7eefe9f7d..eef7e5020 100644
--- a/ext/jni/src/org/sqlite/jni/AuthorizerCallback.java
+++ b/ext/jni/src/org/sqlite/jni/AuthorizerCallback.java
@@ -12,6 +12,7 @@
 ** This file is part of the JNI bindings for the sqlite3 C API.
 */
 package org.sqlite.jni;
+import org.sqlite.jni.annotation.*;
 
 /**
    Callback for use with sqlite3_set_authorizer().
diff --git a/ext/jni/src/org/sqlite/jni/SQLite3Jni.java b/ext/jni/src/org/sqlite/jni/SQLite3Jni.java
index 8777a9abd..1e02b41be 100644
--- a/ext/jni/src/org/sqlite/jni/SQLite3Jni.java
+++ b/ext/jni/src/org/sqlite/jni/SQLite3Jni.java
@@ -138,6 +138,7 @@ public final class SQLite3Jni {
      allocation error. In all casses, 0 is considered the sentinel
      "not a key" value.
   */
+  @Canonical
   public static native long sqlite3_aggregate_context(sqlite3_context cx, boolean initialize);
 
   /**
@@ -156,11 +157,13 @@ public final class SQLite3Jni {
 
      <p>See the AutoExtension class docs for more information.
   */
+  @Canonical
   public static native int sqlite3_auto_extension(@NotNull AutoExtensionCallback callback);
 
   /**
      Results are undefined if data is not null and n<0 || n>=data.length.
   */
+  @Canonical
   public static native int sqlite3_bind_blob(
     @NotNull sqlite3_stmt stmt, int ndx, @Nullable byte[] data, int n
   );
@@ -173,14 +176,17 @@ public final class SQLite3Jni {
       : sqlite3_bind_blob(stmt, ndx, data, data.length);
   }
 
+  @Canonical
   public static native int sqlite3_bind_double(
     @NotNull sqlite3_stmt stmt, int ndx, double v
   );
 
+  @Canonical
   public static native int sqlite3_bind_int(
     @NotNull sqlite3_stmt stmt, int ndx, int v
   );
 
+  @Canonical
   public static native int sqlite3_bind_int64(
     @NotNull sqlite3_stmt stmt, int ndx, long v
   );
@@ -194,10 +200,12 @@ public final class SQLite3Jni {
     @NotNull sqlite3_stmt cx, int ndx, @Nullable Object o
   );
 
+  @Canonical
   public static native int sqlite3_bind_null(
     @NotNull sqlite3_stmt stmt, int ndx
   );
 
+  @Canonical
   public static native int sqlite3_bind_parameter_count(
     @NotNull sqlite3_stmt stmt
   );
@@ -205,10 +213,12 @@ public final class SQLite3Jni {
   /**
      Requires that paramName be a NUL-terminated UTF-8 string.
   */
+  @Canonical
   public static native int sqlite3_bind_parameter_index(
     @NotNull sqlite3_stmt stmt, byte[] paramName
   );
 
+  @Canonical
   public static int sqlite3_bind_parameter_index(
     @NotNull sqlite3_stmt stmt, @NotNull String paramName
   ){
@@ -224,6 +234,7 @@ public final class SQLite3Jni {
      maxBytes>=data.length. If maxBytes is negative then results are
      undefined if data is not null and does not contain a NUL byte.
   */
+  @Canonical
   private static native int sqlite3_bind_text(
     @NotNull sqlite3_stmt stmt, int ndx, @Nullable byte[] data, int maxBytes
   );
@@ -257,6 +268,7 @@ public final class SQLite3Jni {
      signature but requires that its input be encoded in UTF-16 in
      platform byte order.
   */
+  @Canonical
   private static native int sqlite3_bind_text16(
     @NotNull sqlite3_stmt stmt, int ndx, @Nullable byte[] data, int maxBytes
   );
@@ -287,10 +299,12 @@ public final class SQLite3Jni {
       : sqlite3_bind_text16(stmt, ndx, data, data.length);
   }
 
+  @Canonical
   public static native int sqlite3_bind_zeroblob(
     @NotNull sqlite3_stmt stmt, int ndx, int n
   );
 
+  @Canonical
   public static native int sqlite3_bind_zeroblob64(
     @NotNull sqlite3_stmt stmt, int ndx, long n
   );
@@ -300,10 +314,12 @@ public final class SQLite3Jni {
      instance in place of a callback function. Pass it a null handler
      to clear the busy handler.
   */
+  @Canonical
   public static native int sqlite3_busy_handler(
     @NotNull sqlite3 db, @Nullable BusyHandlerCallback handler
   );
 
+  @Canonical
   public static native int sqlite3_busy_timeout(
     @NotNull sqlite3 db, int ms
   );
diff --git a/ext/jni/src/org/sqlite/jni/annotation/Canonical.java b/ext/jni/src/org/sqlite/jni/annotation/Canonical.java
new file mode 100644
index 000000000..260fb2df5
--- /dev/null
+++ b/ext/jni/src/org/sqlite/jni/annotation/Canonical.java
@@ -0,0 +1,16 @@
+package org.sqlite.jni.annotation;
+
+/**
+   This annotation is for marking functions as "canonical", meaning
+   that they exist in the C API. The intent is to distinguish them
+   from functions added specifically to the Java API.
+
+   <p>Canonical functions, unless specifically documented, have the
+   same semantics as their counterparts in @{link
+   https://sqlite.org/c3ref/intro.html the C API documentation}, despite
+   their signatures perhaps differing.
+*/
+@java.lang.annotation.Documented
+@java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE)
+@java.lang.annotation.Target(java.lang.annotation.ElementType.METHOD)
+public @interface Canonical{}
diff --git a/ext/jni/src/org/sqlite/jni/annotation/NotNull.java b/ext/jni/src/org/sqlite/jni/annotation/NotNull.java
index 831f08451..58431e0d9 100644
--- a/ext/jni/src/org/sqlite/jni/annotation/NotNull.java
+++ b/ext/jni/src/org/sqlite/jni/annotation/NotNull.java
@@ -1,4 +1,4 @@
-package org.sqlite.jni;
+package org.sqlite.jni.annotation;
 
 /**
    This annotation is for flagging parameters which may not legally be
diff --git a/ext/jni/src/org/sqlite/jni/annotation/Nullable.java b/ext/jni/src/org/sqlite/jni/annotation/Nullable.java
index 1dbb780d5..187ab263b 100644
--- a/ext/jni/src/org/sqlite/jni/annotation/Nullable.java
+++ b/ext/jni/src/org/sqlite/jni/annotation/Nullable.java
@@ -1,4 +1,4 @@
-package org.sqlite.jni;
+package org.sqlite.jni.annotation;
 
 /**
    This annotation is for flagging parameters which may legally be
diff --git a/ext/jni/src/org/sqlite/jni/fts5_api.java b/ext/jni/src/org/sqlite/jni/fts5_api.java
index 43b3d62de..92ca7c669 100644
--- a/ext/jni/src/org/sqlite/jni/fts5_api.java
+++ b/ext/jni/src/org/sqlite/jni/fts5_api.java
@@ -12,6 +12,7 @@
 ** This file is part of the JNI bindings for the sqlite3 C API.
 */
 package org.sqlite.jni;
+import org.sqlite.jni.annotation.*;
 
 /**
    INCOMPLETE AND COMPLETELY UNTESTED.
diff --git a/ext/jni/src/org/sqlite/jni/fts5_tokenizer.java b/ext/jni/src/org/sqlite/jni/fts5_tokenizer.java
index fd86c2f51..053434e26 100644
--- a/ext/jni/src/org/sqlite/jni/fts5_tokenizer.java
+++ b/ext/jni/src/org/sqlite/jni/fts5_tokenizer.java
@@ -12,6 +12,7 @@
 ** This file is part of the JNI bindings for the sqlite3 C API.
 */
 package org.sqlite.jni;
+import org.sqlite.jni.annotation.*;
 
 /**
    INCOMPLETE AND COMPLETELY UNTESTED.