@adhd/apigen-base-logical 0.1.0 → 0.1.2

package/lib/contracts.d.ts

@@ -28,6 +28,25 @@ export interface LogicalTypeCodec<Host = unknown> {
     readonly schema: SchemaNode;
     /** Structural, cheap test: does this codec own `node`? (format match, or x-apigen-codec===id). */
     matches(node: SchemaNode): boolean;
+    /**
+     * Value-side claim test, used ONLY on the schemaless path (a `{}` / `any`
+     * schema node, where `matches(node)` cannot decide anything).
+     *
+     * Implement this on — and only on — codecs whose HOST type is not
+     * JSON-native (`Date`, `bigint`, `Uint8Array`, non-finite `number`). Those
+     * are the values that genuinely need the `{$apigen,v}` envelope to survive
+     * a JSON round-trip. A codec whose host type IS JSON-native (`uuid` and
+     * `decimal` are both branded strings) must NOT implement it: a plain string
+     * already round-trips, and claiming it would rewrite a consumer's payload
+     * for no gain.
+     *
+     * A codec that omits `ownsValue` is never eligible for schemaless claiming.
+     * That is the safe default — passthrough loses nothing, whereas a wrong
+     * claim silently destroys data.
+     *
+     * MUST be pure and side-effect free.
+     */
+    ownsValue?(value: unknown): boolean;
     /** Host -> wire. MUST NOT mutate `value`; MUST be deterministic. */
     encode(value: Host, node: SchemaNode, ctx: TranscodeCtx): Wire;
     /** Wire -> host. MUST validate-then-construct; MUST be the inverse of `encode` across the vectors. */

package/lib/example.d.ts

@@ -0,0 +1,35 @@
+/** The minimal JSON-Schema-shaped structure this module reads. */
+export interface JsonSchemaLike {
+    type?: string | string[];
+    properties?: Record<string, JsonSchemaLike>;
+    required?: string[];
+    items?: JsonSchemaLike | JsonSchemaLike[];
+    enum?: unknown[];
+    const?: unknown;
+    format?: string;
+    oneOf?: JsonSchemaLike[];
+    anyOf?: JsonSchemaLike[];
+    allOf?: JsonSchemaLike[];
+    $ref?: string;
+    definitions?: Record<string, JsonSchemaLike>;
+    $defs?: Record<string, JsonSchemaLike>;
+    [key: string]: unknown;
+}
+/**
+ * Synthesize a minimal, AJV-plausible example value for `schema`.
+ *
+ * @param schema - The schema fragment to synthesize a value for.
+ * @param root - The document root `$ref`s in `schema` (and its descendants)
+ *   resolve against. Defaults to `schema` itself — correct for the common
+ *   case where `schema` IS the whole self-contained document (apigen always
+ *   composes schemas this way; see module doc).
+ * @param depth - Internal recursion guard; callers never need to pass this.
+ */
+export declare function synthesizeExample(schema: JsonSchemaLike | undefined, root?: JsonSchemaLike, depth?: number): unknown;
+/**
+ * Render `schema`'s synthesized example as a compact `Example: {...}` note,
+ * or `undefined` if there's nothing meaningful to show (schema absent).
+ * Shared rendering so every call site (tool descriptions, validation error
+ * messages) produces byte-identical example text for the same schema.
+ */
+export declare function renderExampleNote(schema: JsonSchemaLike | undefined): string | undefined;

package/lib/hints.d.ts

@@ -15,18 +15,22 @@ export type CanonicalLogicalTypeId = (typeof CANONICAL_LOGICAL_TYPE_IDS)[number]
 export type LanguageTable = Record<CanonicalLogicalTypeId, TemplateCell>;
 /**
  * @stable The host languages for which a template column exists in
- * {@link TEMPLATE_CELLS}.  `'typescript'` and `'python'` are fully filled
- * (§13.2 values verbatim).  `'rust'`, `'go'`, and `'java'` are scaffolded —
- * structure complete, expressions use stable placeholders pending the
- * `lt-host-*` states.
+ * {@link TEMPLATE_CELLS}.  `'typescript'`, `'python'`, and `'java'` (FEAT-APIGEN-001
+ * slice 1/3, 2026-08-06) are fully filled (§13.2 values verbatim / real
+ * Jackson expressions — see the `JAVA_COLUMN` doc comments below).
+ * `'rust'` and `'go'` remain scaffolded — structure complete, expressions
+ * use stable placeholders pending the `lt-host-*` states.
  */
 export type HostLanguage = 'typescript' | 'python' | 'rust' | 'go' | 'java';
 /**
  * @stable The template-cell registry: `[language][logicalTypeId] → TemplateCell`.
  *
- * TypeScript and Python columns are fully filled per DESIGN §13.2 (verbatim
- * expressions).  Rust, Go, and Java columns are scaffolded — structure complete,
- * expressions use `__SCAFFOLD_*__` placeholders pending `lt-host-*` states.
+ * TypeScript, Python, and Java columns are fully filled (TypeScript/Python
+ * per DESIGN §13.2 verbatim expressions; Java per FEAT-APIGEN-001 slice 1/3 —
+ * real Jackson annotation/expression glue, no `__SCAFFOLD_*__` left — see
+ * `JAVA_COLUMN` above). Rust and Go columns remain scaffolded — structure
+ * complete, expressions use `__SCAFFOLD_*__` placeholders pending `lt-host-*`
+ * states.
  *
  * Keyed by {@link HostLanguage}, then by the canonical {@link CanonicalLogicalTypeId}.
  */

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@adhd/apigen-base-logical",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "main": "./index.js",
   "module": "./index.mjs",
-  "typings": "./index.d.ts"
+  "typings": "./index.d.ts",
+  "description": "Logical-type transcoding contracts for apigen",
+  "keywords": [
+    "api",
+    "codegen",
+    "logical-types",
+    "schema",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PseudoSky/adhd.git",
+    "directory": "packages/apigen/apigen-base-logical"
+  },
+  "homepage": "https://github.com/PseudoSky/adhd/tree/main/packages/apigen/apigen-base-logical#readme",
+  "bugs": {
+    "url": "https://github.com/PseudoSky/adhd/issues"
+  }
 }