@rathnasgala2/schemas 2.11.0 → 2.12.0

package/schemas/deployment-receipt.schema.json

@@ -288,24 +288,29 @@
       "type": "string",
       "pattern": "^(?:0|-?[1-9][0-9]*)$",
       "format": "gala-int64",
-      "description": "Canonical signed 64-bit base-10 JSON string."
+      "description": "Canonical signed 64-bit decimal string; range is checked by the semantic validator."
     },
     "nonNegativeInt64": {
       "type": "string",
       "pattern": "^(?:0|[1-9][0-9]*)$",
-      "format": "gala-int64"
+      "format": "gala-int64",
+      "description": "Canonical non-negative signed-64-bit decimal string; range is checked by the semantic validator."
     },
     "positiveInt64": {
       "type": "string",
+      "minLength": 1,
+      "maxLength": 19,
       "pattern": "^[1-9][0-9]*$",
-      "format": "gala-int64"
+      "format": "gala-positive-int64",
+      "x-gala-maximum": "9223372036854775807"
     },
     "githubPositiveDecimal": {
       "type": "string",
       "minLength": 1,
       "maxLength": 20,
       "pattern": "^[1-9][0-9]{0,19}$",
-      "format": "gala-github-positive-uint64"
+      "format": "gala-github-positive-uint64",
+      "x-gala-maximum": "18446744073709551615"
     },
     "githubActionsArtifactId": { "$ref": "#/$defs/githubPositiveDecimal" },
     "lowerHex40": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
@@ -461,7 +466,7 @@
       "pattern": "^[a-z]{3}[1-9][0-9]?$",
       "x-gala-asciiByteLength": { "minimum": 4, "maximum": 5 }
     },
-    "renderPolicyIdentity": {
+    "recordRenderPolicyIdentity": {
       "type": "object",
       "required": ["name", "version", "digest"],
       "properties": {
@@ -1543,7 +1548,7 @@
       "pattern": "^(?:gala:expect-nothing-served|[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$",
       "description": "Activation fence: a generation identity, or the explicit expect-nothing-served sentinel. Never null, and never absent as a way of saying \"no expectation\" (LOCAL-47). This is the write-side expectation a caller states before it mutates a destination, and it is deliberately asymmetric with the observation-side fields (`observedGenerationId`), which are simply absent -- and are modelled as nullable by the in-process adapter protocol -- when nothing is served (LOCAL-52). It is deliberately one string schema with one combined pattern rather than a two-member `oneOf` of two string schemas: the admitted value set is identical, and OpenAPI Generator 7.25 turns such a union into an empty marker interface that a caller cannot carry a value in."
     },
-    "reproducibleBuildRecord": {
+    "recordReproducibleBuildRecord": {
       "type": "object",
       "required": [
         "repositoryId",
@@ -1628,7 +1633,7 @@
         "policyReleaseId": { "$ref": "#/$defs/stableId" },
         "buildPolicyDecisionDigest": { "$ref": "#/$defs/digest" },
         "stylingContractDigest": { "$ref": "#/$defs/digest" },
-        "renderPolicy": { "$ref": "#/$defs/renderPolicyIdentity" },
+        "renderPolicy": { "$ref": "#/$defs/recordRenderPolicyIdentity" },
         "workflowIdentity": { "$ref": "#/$defs/digest" }
       },
       "additionalProperties": false

package/schemas/navigation.schema.json

@@ -169,16 +169,8 @@
             "properties": { "type": { "const": "internal" } },
             "required": ["type"]
           },
-          "then": {
-            "properties": { "route": {} },
-            "required": ["route"],
-            "not": { "properties": { "url": {} }, "required": ["url"] }
-          },
-          "else": {
-            "properties": { "url": {} },
-            "required": ["url"],
-            "not": { "properties": { "route": {} }, "required": ["route"] }
-          }
+          "then": { "required": ["route"], "not": { "required": ["url"] } },
+          "else": { "required": ["url"], "not": { "required": ["route"] } }
         }
       ]
     },
@@ -190,12 +182,7 @@
         "label": { "$ref": "#/$defs/plainLabel" },
         "route": { "$ref": "#/$defs/canonicalRoute" },
         "url": { "$ref": "#/$defs/urlHttps" },
-        "children": {
-          "type": "array",
-          "items": {},
-          "minItems": 0,
-          "maxItems": 0
-        }
+        "children": { "const": [] }
       },
       "additionalProperties": false,
       "allOf": [
@@ -204,16 +191,8 @@
             "properties": { "type": { "const": "internal" } },
             "required": ["type"]
           },
-          "then": {
-            "properties": { "route": {} },
-            "required": ["route"],
-            "not": { "properties": { "url": {} }, "required": ["url"] }
-          },
-          "else": {
-            "properties": { "url": {} },
-            "required": ["url"],
-            "not": { "properties": { "route": {} }, "required": ["route"] }
-          }
+          "then": { "required": ["route"], "not": { "required": ["url"] } },
+          "else": { "required": ["url"], "not": { "required": ["route"] } }
         }
       ]
     },

package/schemas/theme-contract.schema.json

@@ -593,9 +593,11 @@
     },
     "positiveInt64": {
       "type": "string",
+      "minLength": 1,
+      "maxLength": 19,
       "pattern": "^[1-9][0-9]*$",
-      "format": "gala-int64",
-      "description": "Canonical positive signed-64-bit decimal string; range is checked by the semantic validator."
+      "format": "gala-positive-int64",
+      "x-gala-maximum": "9223372036854775807"
     },
     "nonNegativeInt64": {
       "type": "string",

package/src/index.js

@@ -7,7 +7,7 @@
 import {
   REGISTERED_SCHEMA_IDS,
   validateRegisteredDocument,
-} from './internal/schema-validator.js';
+} from './internal/browser-schema-validator.js';
 
 /** Exact immutable identities accepted by the validator registry. */
 export const GALA_SCHEMA_IDS = REGISTERED_SCHEMA_IDS;
@@ -17,7 +17,7 @@ export const GALA_SCHEMA_IDS = REGISTERED_SCHEMA_IDS;
  *
  * @param {string} schemaId exact immutable schema identity
  * @param {unknown} value document value
- * @returns {import('./internal/schema-validator.js').GalaValidationResult} validation result
+ * @returns {import('./internal/browser-schema-validator.js').GalaValidationResult} validation result
  */
 export function validateGalaDocument(schemaId, value) {
   return validateRegisteredDocument(schemaId, value);

package/src/internal/browser-schema-validator.js

@@ -0,0 +1,43 @@
+/**
+ * The public `.` export's validator suite, bound to the precompiled browser
+ * standalone core (SCH-C2) instead of a runtime `ajv.compile()`.
+ *
+ * `src/internal/schema-validator.js` -- the runtime-compiled equivalent --
+ * stays in place for `scripts/validator-parity.mjs` (the Node-only fixture
+ * and cross-language parity tooling), which additionally needs fragment-
+ * and cardinality-level validation the precompiled core does not carry.
+ * The public `.` export only ever needed whole-document validation, so it
+ * moves to this module instead.
+ *
+ * @module
+ */
+
+import diagnosticMap from '../../diagnostics/diagnostic-map.json' with { type: 'json' };
+import { SCHEMA_VALIDATORS } from '../../generated/browser/validator-core.mjs';
+import { createPrecompiledValidatorSuite } from './validator-core.js';
+
+const SUITE = createPrecompiledValidatorSuite({
+  validators: SCHEMA_VALIDATORS,
+  diagnosticMap: /** @type {import('./validator-core.js').DiagnosticMap} */ (
+    diagnosticMap
+  ),
+});
+
+/**
+ * @typedef {import('./validator-core.js').GalaDiagnostic} GalaDiagnostic
+ * @typedef {import('./validator-core.js').GalaValidationResult} GalaValidationResult
+ */
+
+/** Exact immutable identities accepted by the public registry. */
+export const REGISTERED_SCHEMA_IDS = SUITE.schemaIds;
+
+/**
+ * Validate one complete Gala document and return stable diagnostics.
+ *
+ * @param {string} schemaId exact immutable schema identity
+ * @param {unknown} value document value
+ * @returns {GalaValidationResult} validation result
+ */
+export function validateRegisteredDocument(schemaId, value) {
+  return SUITE.validateDocument(schemaId, value);
+}

package/src/internal/format-validators.js

@@ -5,7 +5,7 @@ import { validateSpdxExpression } from './spdx.js';
  * Validate one custom Gala string format for fixture generation and audits.
  * Unknown format names fail closed.
  *
- * The complete 19-contract surface needs `gala-spdx-expression`, so this
+ * The complete 20-contract surface needs `gala-spdx-expression`, so this
  * module adds that one branch on top of the browser-light core dispatcher and
  * delegates everything else unchanged. Importing this module pulls in the
  * pinned SPDX licence list; importing the core does not.

package/src/internal/gala-keywords.js

@@ -0,0 +1,148 @@
+/**
+ * Pure implementations of Gala's `x-gala-*` assertion keywords.
+ *
+ * This is the single source of truth for what each keyword means; it is
+ * consumed two ways, by two different Ajv wiring styles that cannot share
+ * more than this:
+ *
+ * - `validator-core.js`'s `addGalaKeywords` wraps each function in a
+ *   closure-based `ajv.addKeyword({validate: ...})` for the runtime-compiled
+ *   registry used by the Node-only fixture and parity tooling.
+ * - `codegen/generate-contracts.ts`'s browser core generator wraps each
+ *   function in a `code`-based `ajv.addKeyword({code: ...})` definition, so
+ *   Ajv's standalone output calls these functions directly by their real
+ *   ESM import instead of trying to serialize a closure (SCH-C2).
+ *
+ * @module
+ */
+
+import { canonicalizeJcsBytes } from './canonical-jcs.js';
+import { utf8Bytes } from './bytes.js';
+import { assertUnicodeScalarString, graphemeLength17 } from './unicode17.js';
+
+/**
+ * Test inclusive bounds.
+ *
+ * @param {number} value measured value
+ * @param {{minimum?: number, maximum?: number}} bounds inclusive bounds
+ * @returns {boolean} whether the value is in range
+ */
+function withinBounds(value, bounds) {
+  return (
+    (bounds.minimum === undefined || value >= bounds.minimum) &&
+    (bounds.maximum === undefined || value <= bounds.maximum)
+  );
+}
+
+/**
+ * `x-gala-asciiByteLength`: every scalar is ASCII and the byte (== code
+ * unit, for ASCII) length is within bounds.
+ *
+ * @param {{minimum?: number, maximum?: number}} bounds declared bounds
+ * @param {string} value candidate string
+ * @returns {boolean} whether the value satisfies the keyword
+ */
+export function galaAsciiByteLength(bounds, value) {
+  return (
+    [...value].every((character) => character.charCodeAt(0) <= 0x7f) &&
+    withinBounds(value.length, bounds)
+  );
+}
+
+/**
+ * `x-gala-utf8ByteLength`: the value is Unicode-scalar-clean and its UTF-8
+ * byte length is within bounds.
+ *
+ * @param {{minimum?: number, maximum?: number}} bounds declared bounds
+ * @param {string} value candidate string
+ * @returns {boolean} whether the value satisfies the keyword
+ */
+export function galaUtf8ByteLength(bounds, value) {
+  try {
+    assertUnicodeScalarString(value);
+    return withinBounds(utf8Bytes(value).length, bounds);
+  } catch (error) {
+    if (
+      error instanceof TypeError &&
+      error.message === 'UNICODE_SCALAR_INVALID'
+    ) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * `x-gala-graphemeLength`: the UAX #29 extended grapheme cluster count is
+ * within bounds.
+ *
+ * @param {{minimum?: number, maximum?: number}} bounds declared bounds
+ * @param {string} value candidate string
+ * @returns {boolean} whether the value satisfies the keyword
+ */
+export function galaGraphemeLength(bounds, value) {
+  try {
+    return withinBounds(graphemeLength17(value), bounds);
+  } catch (error) {
+    if (
+      error instanceof TypeError &&
+      error.message === 'UNICODE_SCALAR_INVALID'
+    ) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * `x-gala-maxCanonicalBytes`: the RFC 8785 JCS-canonicalized byte length of
+ * the whole value does not exceed the declared maximum.
+ *
+ * @param {number} maximum declared inclusive maximum
+ * @param {unknown} value candidate value
+ * @returns {boolean} whether the value satisfies the keyword
+ */
+export function galaMaxCanonicalBytes(maximum, value) {
+  try {
+    return canonicalizeJcsBytes(value).byteLength <= maximum;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `x-gala-maximum`: the value, read as a non-negative decimal integer, does
+ * not exceed the declared maximum.
+ *
+ * Fails closed (SCH-H13): a range assertion in a package whose README
+ * describes it as fail-closed must reject what it cannot evaluate rather
+ * than defer to a pattern/format keyword that may not be present on every
+ * `$def` using this keyword (see SCH-C3).
+ *
+ * @param {number | string} maximum declared inclusive maximum
+ * @param {unknown} value candidate value
+ * @returns {boolean} whether the value satisfies the keyword
+ */
+export function galaMaximum(maximum, value) {
+  if (typeof value !== 'string' && typeof value !== 'number') return false;
+  if (typeof value === 'string' && !/^(?:0|[1-9][0-9]*)$/u.test(value)) {
+    return false;
+  }
+  try {
+    return BigInt(value) <= BigInt(maximum);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `x-gala-decision-phase`: pure annotation, not an assertion. It marks
+ * which DEC-097 lifecycle phase (issuance vs. deploy) a property belongs to
+ * for digest scoping (see LOCAL-62 in README.md) and carries no independent
+ * validation rule of its own.
+ *
+ * @returns {true} always valid
+ */
+export function galaDecisionPhase() {
+  return true;
+}