@entelekheia/ref-id 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entelekheia/ref-id",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "The ref: identifier scheme — a specification published as data with conformance vectors, and the package that consumes it.",
   "type": "module",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org",
-    "provenance": false
+    "provenance": true
   },
   "repository": {
     "type": "git",

package/spec/ref-id.json

@@ -1,5 +1,5 @@
 {
-  "specVersion": "1.1.0",
+  "specVersion": "1.2.0",
   "scheme": "ref",
   "grammar": {
     "dialect": "ecmascript-2018",
@@ -128,6 +128,14 @@
       "declaredBy": "the agent identifier grammar namespace/name[:version]: the namespace is a domain, a platform/user under a domain, a mailbox, or the literal unknown; the ~digest of the full form is carried by state= instead",
       "corpus": "the agent bundle",
       "reference": "dot-agent agent-id reference"
+    },
+    "ai-model": {
+      "locator": "served-model-id",
+      "validator": "declared-name",
+      "delegate": "verbatim",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]*(?:/[A-Za-z0-9][A-Za-z0-9._:@-]*)*$",
+      "declaredBy": "the id the model is served under — the exact string a caller sends to the serving process to select it, verbatim. Deliberately permissive: coercing a served name breaks the round-trip that makes it an identifier at all, so ':' (an Ollama tag), '/' (a hub-style namespace) and '@' (an LM Studio quantisation key, a revision pin) are all admitted, because a serving process accepts each of them today and rejecting one would be a defect rather than a safeguard. Every '/'-separated segment must open on an alphanumeric, which admits each of those and excludes '..', '//' and a trailing '/': the delegate is verbatim, so a consumer mapping a served id onto a path — a local weights cache — would otherwise inherit a traversal from a locator that parsed clean. Case is significant and there is no normalisation, which is a decision with no way back: two callers naming one model in two casings mint two identifiers, and adding a fold later would be a change to normalisation, which mints identifier version 2.",
+      "reference": "no published grammar names a hosted API model: Package URL registers artifact-registry namespaces only (huggingface, mlflow), CycloneDX carries the category as a component type and identifies with an ordinary purl, SPDX 3.0's AIPackage identifies by free-text name and delegates to packageUrl, and OpenTelemetry's gen_ai.request.model is explicitly free text — so this type is this specification's own, not a delegation."
     }
   },
   "typeRegistry": "a type names the naming system that owns the locator grammar; an unregistered type parses to uncovered, never to malformed, and registering its validator here is what promotes it — the registry is this table",
@@ -190,7 +198,8 @@
       "role": "population",
       "forms": [
         "ref",
-        "sha256"
+        "sha256",
+        "unknown"
       ]
     },
     "when": {
@@ -229,6 +238,10 @@
       "nested": true,
       "depth": 1,
       "encoding": "nested"
+    },
+    "unknown": {
+      "pattern": "^unknown$",
+      "reference": "the declared level for a population nobody established. Deliberately not `none`, which `state` uses: a state cannot be empty, so `none` is unambiguous there, while a population over zero members is a real and different thing from a population nobody recorded — and an identifier must not let the two read alike. It is a floor, never a destination: a producer that can enumerate its population says so with `sha256`, which names which population rather than admitting there was one"
     }
   },
   "refinements": {
@@ -1127,6 +1140,259 @@
           "status": "malformed",
           "part": "locator"
         }
+      },
+      {
+        "name": "ai-model served id is admitted: Qwen3-4B-Instruct-2507-4bit",
+        "input": "ref:ai-model:Qwen3-4B-Instruct-2507-4bit",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "Qwen3-4B-Instruct-2507-4bit"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: gemma-4-26b-a4b-it-4bit",
+        "input": "ref:ai-model:gemma-4-26b-a4b-it-4bit",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "gemma-4-26b-a4b-it-4bit"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: Qwen3.5-9B-OptiQ-4bit",
+        "input": "ref:ai-model:Qwen3.5-9B-OptiQ-4bit",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "Qwen3.5-9B-OptiQ-4bit"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: gpt-oss-20b-MXFP4-Q8",
+        "input": "ref:ai-model:gpt-oss-20b-MXFP4-Q8",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "gpt-oss-20b-MXFP4-Q8"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: Llama-3.2-1B-Instruct-4bit",
+        "input": "ref:ai-model:Llama-3.2-1B-Instruct-4bit",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "Llama-3.2-1B-Instruct-4bit"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: Qwen3.5-27B-Claude-4.6-Opus-Distilled-MLX-4bit",
+        "input": "ref:ai-model:Qwen3.5-27B-Claude-4.6-Opus-Distilled-MLX-4bit",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "Qwen3.5-27B-Claude-4.6-Opus-Distilled-MLX-4bit"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: SmolLM3-3B-4bit",
+        "input": "ref:ai-model:SmolLM3-3B-4bit",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "SmolLM3-3B-4bit"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: T-mixed-gemma-4-12B-it-OptiQ-4bit",
+        "input": "ref:ai-model:T-mixed-gemma-4-12B-it-OptiQ-4bit",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "T-mixed-gemma-4-12B-it-OptiQ-4bit"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: claude-opus-5",
+        "input": "ref:ai-model:claude-opus-5",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "claude-opus-5"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: Ternary-Bonsai-27B-mlx-2bit",
+        "input": "ref:ai-model:Ternary-Bonsai-27B-mlx-2bit",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "Ternary-Bonsai-27B-mlx-2bit"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: gemini-2.5-flash",
+        "input": "ref:ai-model:gemini-2.5-flash",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "gemini-2.5-flash"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: llama3:8b",
+        "input": "ref:ai-model:llama3:8b",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "llama3:8b"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: gpt-4o-2024-08-06",
+        "input": "ref:ai-model:gpt-4o-2024-08-06",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "gpt-4o-2024-08-06"
+        }
+      },
+      {
+        "name": "ai-model served id is admitted: mlx-community/Qwen3-1.7B-4bit",
+        "input": "ref:ai-model:mlx-community/Qwen3-1.7B-4bit",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [],
+          "fragment": null,
+          "type": "ai-model",
+          "locator": "mlx-community/Qwen3-1.7B-4bit"
+        }
+      },
+      {
+        "name": "an ai-model id cannot open on a separator",
+        "input": "ref:ai-model:-Qwen3-4B",
+        "expect": {
+          "status": "malformed",
+          "part": "locator"
+        }
+      },
+      {
+        "name": "unknown is a declared population level",
+        "input": "ref:folder:acme-tools;over=unknown",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "qualifiers": [
+            [
+              "over",
+              "unknown"
+            ]
+          ],
+          "fragment": null,
+          "type": "folder",
+          "locator": "acme-tools"
+        }
+      },
+      {
+        "name": "none is not a population level — a population of zero is not a population nobody recorded",
+        "input": "ref:folder:acme-tools;over=none",
+        "expect": {
+          "status": "malformed",
+          "part": "over"
+        }
+      },
+      {
+        "name": "unknown is not a state level — the fence from the other side",
+        "input": "ref:folder:acme-tools;state=unknown",
+        "expect": {
+          "status": "malformed",
+          "part": "state"
+        }
+      },
+      {
+        "name": "unknown is declared for over alone, never for by",
+        "input": "ref:folder:acme-tools;by=unknown",
+        "expect": {
+          "status": "malformed",
+          "part": "by"
+        }
+      },
+      {
+        "name": "an ai-model id cannot carry a character outside its declared class",
+        "input": "ref:ai-model:a b",
+        "expect": {
+          "status": "malformed",
+          "part": "locator"
+        }
+      },
+      {
+        "name": "an ai-model id carries a quantisation key after @",
+        "input": "ref:ai-model:qwen2.5-7b-instruct@q4_k_m",
+        "expect": {
+          "status": "ok",
+          "version": 1,
+          "type": "ai-model",
+          "locator": "qwen2.5-7b-instruct@q4_k_m",
+          "qualifiers": [],
+          "fragment": null
+        }
+      },
+      {
+        "name": "an ai-model id cannot traverse — every segment opens on an alphanumeric",
+        "input": "ref:ai-model:a/../../etc/passwd",
+        "expect": {
+          "status": "malformed",
+          "part": "locator"
+        }
+      },
+      {
+        "name": "an ai-model id cannot carry an empty segment",
+        "input": "ref:ai-model:a//b",
+        "expect": {
+          "status": "malformed",
+          "part": "locator"
+        }
       }
     ],
     "roundtrip": [
@@ -1149,7 +1415,10 @@
       "ref:pkg:npm/acme-tools#acme/adr@2/0019",
       "ref:folder:acme-tools;by=ref:2:pkg:npm/x@1.0.0",
       "ref:doi:10.1000/182;state=swh:1:rev:7e29bb6000000000000000000000000000000000#S",
-      "ref:folder:acme-tools;by=ref:pkg:npm/x@1.0.0%2523src/y"
+      "ref:folder:acme-tools;by=ref:pkg:npm/x@1.0.0%2523src/y",
+      "ref:ai-model:mlx-community/Qwen3-1.7B-4bit",
+      "ref:ai-model:llama3:8b",
+      "ref:folder:acme-tools;over=unknown"
     ],
     "build": [
       {
@@ -1300,6 +1569,36 @@
           ]
         },
         "expect": "ref:folder:acme-tools;over=sha256:41b9caaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+      },
+      {
+        "name": "an ai-model locator with a hub-style separator builds as is",
+        "parts": {
+          "type": "ai-model",
+          "locator": "mlx-community/Qwen3-1.7B-4bit"
+        },
+        "expect": "ref:ai-model:mlx-community/Qwen3-1.7B-4bit"
+      },
+      {
+        "name": "an ai-model locator with an Ollama tag builds as is",
+        "parts": {
+          "type": "ai-model",
+          "locator": "llama3:8b"
+        },
+        "expect": "ref:ai-model:llama3:8b"
+      },
+      {
+        "name": "over=unknown builds as the declared level for an unestablished population",
+        "parts": {
+          "type": "folder",
+          "locator": "acme-tools",
+          "qualifiers": [
+            [
+              "over",
+              "unknown"
+            ]
+          ]
+        },
+        "expect": "ref:folder:acme-tools;over=unknown"
       }
     ],
     "digest": [

package/spec/ref-id.json.sha256

@@ -1 +1 @@
-c58f36a43416e5422235e8d92920d4d82581601deed69169901291938c5e2727
+ee34597292d313a7c424d09c050d2e1bf6cc9507b9b2627f63c684131c6fd3c6