Add Stage 4 kind discrimination and Stage 5 schema validators

Implement closed-schema validation for all three document kinds (section 02,
section 06, section 07, section 08) and the cross-field semantic checks the
Stage 5 definition assigns:
- closed-schema discipline (unknown field, missing required, no null literal);
- reusable field validators: slug, RFC 3339 timestamp form, content path syntax,
  strict base64url length, NFC for user-visible text, control-character rules,
  byte-length caps, integer range;
- the eleven block kinds with inline content, marks, link targets, form fields,
  and the submit_form-not-in-transaction rule;
- manifest origin.not_after vs canary.issued_at bounds (E_ORIGIN_INVALID with
  reason), the state_policy submit-budget aggregate (E_SUBMIT_BUDGET, exact wire
  byte arithmetic), and manifest.updated future-skew (E_SCHEMA_FIELD_SYNTAX);
- Stage 4 kind discrimination (spec_version, kind, sig presence and values).

The integer grammar runs as a whole-document Stage 5 pre-pass before
closed-schema field checks, per section 04's requirement to validate numeric
tokens before any conversion; corpus vector 140 fixes this ordering.

Tests drive the Stage 4 and Stage 5 corpus vectors and confirm the seven accept
vectors pass schema validation cleanly.

Author: samjanny

src/main/java/org/entangled/pipeline/Stage4Kind.java

@@ -0,0 +1,58 @@
+package org.entangled.pipeline;
+
+import org.entangled.DiagnosticCode;
+import org.entangled.RejectException;
+import org.entangled.json.JsonValue;
+
+/**
+ * Stage 4 document-kind discrimination (section 10, section 02):
+ * <ul>
+ *   <li>{@code spec_version}, {@code kind}, and {@code sig} are present and have
+ *       the right primitive type (string), else {@code E_KIND_MISSING_FIELDS};</li>
+ *   <li>{@code spec_version} is exactly {@code "1.0"}, else
+ *       {@code E_KIND_SPEC_VERSION};</li>
+ *   <li>{@code kind} is one of {@code manifest}/{@code content}/{@code transaction},
+ *       else {@code E_KIND_UNKNOWN}.</li>
+ * </ul>
+ *
+ * <p>This obtains the minimum needed to select a schema for Stage 5; full
+ * closed-schema validation happens there.
+ */
+public final class Stage4Kind {
+
+    /** The three document kinds. */
+    public enum Kind { MANIFEST, CONTENT, TRANSACTION }
+
+    private Stage4Kind() {
+    }
+
+    public static Kind discriminate(JsonValue root) {
+        if (!(root instanceof JsonValue.Obj obj)) {
+            // The top-level document must be a JSON object.
+            throw new RejectException(DiagnosticCode.E_KIND_MISSING_FIELDS);
+        }
+        String specVersion = requireString(obj, "spec_version");
+        requireString(obj, "kind");
+        requireString(obj, "sig");
+
+        if (!specVersion.equals("1.0")) {
+            throw new RejectException(DiagnosticCode.E_KIND_SPEC_VERSION);
+        }
+        String kind = ((JsonValue.Str) obj.get("kind")).value();
+        return switch (kind) {
+            case "manifest" -> Kind.MANIFEST;
+            case "content" -> Kind.CONTENT;
+            case "transaction" -> Kind.TRANSACTION;
+            default -> throw new RejectException(DiagnosticCode.E_KIND_UNKNOWN);
+        };
+    }
+
+    private static String requireString(JsonValue.Obj obj, String key) {
+        JsonValue v = obj.get(key);
+        if (!(v instanceof JsonValue.Str s)) {
+            // Absent or wrong primitive type.
+            throw new RejectException(DiagnosticCode.E_KIND_MISSING_FIELDS);
+        }
+        return s.value();
+    }
+}

src/main/java/org/entangled/schema/Blocks.java

@@ -0,0 +1,264 @@
+package org.entangled.schema;
+
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import org.entangled.DiagnosticCode;
+import org.entangled.RejectException;
+import org.entangled.json.JsonValue;
+
+/**
+ * Block-grammar validation for the eleven block kinds, section 03.
+ *
+ * <p>Each block is validated against the closed schema for its declared
+ * {@code kind}; an unknown kind is {@code E_SCHEMA_ENUM_VIOLATION}. A
+ * {@code submit_form} block in a transaction document is
+ * {@code E_SCHEMA_BLOCK_NOT_PERMITTED}. Inline content is validated by
+ * {@link Inline}; per-block aggregate byte caps are enforced here.
+ */
+public final class Blocks {
+
+    private static final Set<String> KNOWN_KINDS = Set.of(
+            "paragraph", "heading", "code_block", "quote", "list", "divider",
+            "image", "link", "submit_form", "feedback", "note");
+
+    private static final Set<String> FEEDBACK_VARIANTS = Set.of("success", "info", "warning", "error");
+    private static final Set<String> NOTE_VARIANTS = Set.of("info", "warning", "danger", "success");
+    private static final Set<String> MEDIA_TYPES = Set.of("image/png", "image/jpeg", "image/webp");
+    private static final Set<String> FIELD_KINDS = Set.of("text", "textarea", "select", "checkbox");
+
+    private Blocks() {
+    }
+
+    /** Validate one block. {@code transaction} selects document-kind permission rules. */
+    public static void validate(JsonValue blockValue, boolean transaction) {
+        JsonValue.Obj b = Fields.obj(blockValue);
+        String kind = Fields.str(Inline.require(b, "kind"));
+        if (!KNOWN_KINDS.contains(kind)) {
+            throw new RejectException(DiagnosticCode.E_SCHEMA_ENUM_VIOLATION);
+        }
+        if (transaction && kind.equals("submit_form")) {
+            throw new RejectException(DiagnosticCode.E_SCHEMA_BLOCK_NOT_PERMITTED);
+        }
+        switch (kind) {
+            case "paragraph" -> paragraph(b);
+            case "heading" -> heading(b);
+            case "code_block" -> codeBlock(b);
+            case "quote" -> quote(b);
+            case "list" -> list(b);
+            case "divider" -> divider(b);
+            case "image" -> image(b);
+            case "link" -> link(b);
+            case "submit_form" -> submitForm(b);
+            case "feedback" -> feedback(b);
+            case "note" -> note(b);
+            default -> throw new RejectException(DiagnosticCode.E_SCHEMA_ENUM_VIOLATION);
+        }
+    }
+
+    private static void paragraph(JsonValue.Obj b) {
+        Closed.check(b, Set.of("kind", "content"), Set.of("kind", "content"));
+        int bytes = Inline.validate(b.get("content"), true, true);
+        cap(bytes, 8 * 1024);
+    }
+
+    private static void heading(JsonValue.Obj b) {
+        Closed.check(b, Set.of("kind", "level", "content"), Set.of("kind", "level", "content"));
+        Fields.integerInRange(b.get("level"), 1, 6);
+        int bytes = Inline.validate(b.get("content"), true, true);
+        cap(bytes, 200);
+    }
+
+    private static void codeBlock(JsonValue.Obj b) {
+        Closed.check(b, Set.of("kind", "language", "content"), Set.of("kind", "language", "content"));
+        slugLanguage(Fields.str(b.get("language")));
+        String content = Fields.str(b.get("content"));
+        if (Fields.utf8Len(content) > 32 * 1024) {
+            throw new RejectException(DiagnosticCode.E_SCHEMA_FIELD_LENGTH);
+        }
+        // Control chars other than line feed are forbidden; NFC required (section 04).
+        Fields.noControlChars(content, true);
+        Fields.requireNfc(content);
+    }
+
+    private static void quote(JsonValue.Obj b) {
+        Closed.check(b, Set.of("kind", "content", "attribution"), Set.of("kind", "content"));
+        int bytes = Inline.validate(b.get("content"), true, true);
+        cap(bytes, 4 * 1024);
+        if (b.has("attribution")) {
+            int abytes = Inline.validate(b.get("attribution"), true, true);
+            cap(abytes, 200);
+        }
+    }
+
+    private static void list(JsonValue.Obj b) {
+        Closed.check(b, Set.of("kind", "ordered", "items"), Set.of("kind", "ordered", "items"));
+        Fields.bool(b.get("ordered"));
+        List<JsonValue> items = Fields.arr(b.get("items")).elements();
+        if (items.isEmpty() || items.size() > 64) {
+            throw new RejectException(DiagnosticCode.E_SCHEMA_FIELD_LENGTH);
+        }
+        int total = 0;
+        for (JsonValue item : items) {
+            total += Inline.validate(item, true, true);
+        }
+        cap(total, 8 * 1024);
+    }
+
+    private static void divider(JsonValue.Obj b) {
+        Closed.check(b, Set.of("kind"), Set.of("kind"));
+    }
+
+    private static void image(JsonValue.Obj b) {
+        Closed.check(b,
+                Set.of("kind", "src", "sha256", "media_type", "width", "height", "alt", "caption"),
+                Set.of("kind", "src", "sha256", "media_type", "width", "height", "alt"));
+        Fields.path(Fields.str(b.get("src")));
+        sha256Field(Fields.str(b.get("sha256")));
+        Fields.inEnum(Fields.str(b.get("media_type")), MEDIA_TYPES);
+        Fields.integerInRange(b.get("width"), 1, 4096);
+        Fields.integerInRange(b.get("height"), 1, 4096);
+        String alt = Fields.str(b.get("alt"));
+        Fields.maxBytes(alt, 1024);
+        Fields.noControlChars(alt, false);
+        Fields.requireNfc(alt);
+        if (b.has("caption")) {
+            String caption = Fields.str(b.get("caption"));
+            if (caption.isEmpty()) {
+                // An empty caption must be omitted, not present as "".
+                throw Fields.syntax();
+            }
+            Fields.maxBytes(caption, 500);
+            Fields.noControlChars(caption, false);
+            Fields.requireNfc(caption);
+        }
+    }
+
+    private static void link(JsonValue.Obj b) {
+        Closed.check(b, Set.of("kind", "label", "target"), Set.of("kind", "label", "target"));
+        // link.label is inline content that MUST NOT contain link elements.
+        int bytes = Inline.validate(b.get("label"), false, true);
+        cap(bytes, 200);
+        Inline.validateTarget(b.get("target"));
+    }
+
+    private static void submitForm(JsonValue.Obj b) {
+        Closed.check(b, Set.of("kind", "label", "submit_to", "fields", "submit_label"),
+                Set.of("kind", "label", "submit_to", "fields", "submit_label"));
+        Inline.validate(b.get("label"), false, true);
+        Fields.path(Fields.str(b.get("submit_to")));
+        List<JsonValue> fields = Fields.arr(b.get("fields")).elements();
+        if (fields.isEmpty() || fields.size() > 16) {
+            throw new RejectException(DiagnosticCode.E_SCHEMA_FIELD_LENGTH);
+        }
+        Set<String> names = new HashSet<>();
+        for (JsonValue f : fields) {
+            String name = formField(Fields.obj(f));
+            if (!names.add(name)) {
+                throw new RejectException(DiagnosticCode.E_SCHEMA_DUPLICATE_ENTRY);
+            }
+        }
+        String submitLabel = Fields.str(b.get("submit_label"));
+        Fields.maxBytes(submitLabel, 100);
+        Fields.noControlChars(submitLabel, false);
+    }
+
+    private static String formField(JsonValue.Obj f) {
+        String kind = Fields.str(Inline.require(f, "kind"));
+        Fields.inEnum(kind, FIELD_KINDS);
+        String name;
+        switch (kind) {
+            case "text", "textarea" -> {
+                Closed.check(f, Set.of("kind", "name", "label", "required", "max_length"),
+                        Set.of("kind", "name", "label", "required", "max_length"));
+                name = sharedFormFields(f);
+                Fields.integerInRange(f.get("max_length"), 1, 8192);
+            }
+            case "select" -> {
+                Closed.check(f, Set.of("kind", "name", "label", "required", "options"),
+                        Set.of("kind", "name", "label", "required", "options"));
+                name = sharedFormFields(f);
+                selectOptions(f.get("options"));
+            }
+            case "checkbox" -> {
+                Closed.check(f, Set.of("kind", "name", "label", "required"),
+                        Set.of("kind", "name", "label", "required"));
+                name = sharedFormFields(f);
+            }
+            default -> throw new RejectException(DiagnosticCode.E_SCHEMA_ENUM_VIOLATION);
+        }
+        return name;
+    }
+
+    private static String sharedFormFields(JsonValue.Obj f) {
+        String name = Fields.str(f.get("name"));
+        Fields.slug(name, 64);
+        String label = Fields.str(f.get("label"));
+        Fields.maxBytes(label, 200);
+        Fields.noControlChars(label, false);
+        Fields.bool(f.get("required"));
+        return name;
+    }
+
+    private static void selectOptions(JsonValue optionsValue) {
+        List<JsonValue> options = Fields.arr(optionsValue).elements();
+        if (options.isEmpty() || options.size() > 32) {
+            throw new RejectException(DiagnosticCode.E_SCHEMA_FIELD_LENGTH);
+        }
+        Set<String> values = new HashSet<>();
+        for (JsonValue o : options) {
+            JsonValue.Obj opt = Fields.obj(o);
+            Closed.check(opt, Set.of("value", "label"), Set.of("value", "label"));
+            String value = Fields.str(opt.get("value"));
+            Fields.slug(value, 64);
+            if (!values.add(value)) {
+                throw new RejectException(DiagnosticCode.E_SCHEMA_DUPLICATE_ENTRY);
+            }
+            String label = Fields.str(opt.get("label"));
+            Fields.maxBytes(label, 200);
+            Fields.noControlChars(label, false);
+        }
+    }
+
+    private static void feedback(JsonValue.Obj b) {
+        Closed.check(b, Set.of("kind", "variant", "content"), Set.of("kind", "variant", "content"));
+        Fields.inEnum(Fields.str(b.get("variant")), FEEDBACK_VARIANTS);
+        int bytes = Inline.validate(b.get("content"), true, true);
+        cap(bytes, 2 * 1024);
+    }
+
+    private static void note(JsonValue.Obj b) {
+        Closed.check(b, Set.of("kind", "variant", "title", "content"), Set.of("kind", "variant", "content"));
+        Fields.inEnum(Fields.str(b.get("variant")), NOTE_VARIANTS);
+        if (b.has("title")) {
+            String title = Fields.str(b.get("title"));
+            if (title.isEmpty()) {
+                throw Fields.syntax();
+            }
+            Fields.maxBytes(title, 200);
+            Fields.noControlChars(title, false);
+            Fields.requireNfc(title);
+        }
+        int bytes = Inline.validate(b.get("content"), true, true);
+        cap(bytes, 4 * 1024);
+    }
+
+    private static void slugLanguage(String language) {
+        // code_block.language: [a-z0-9_-], begins [a-z0-9], non-empty, <= 64.
+        Fields.slug(language, 64);
+    }
+
+    private static void sha256Field(String s) {
+        // "sha-256:" + 43 base64url chars = 51 chars total.
+        if (s.length() != 51 || !s.startsWith("sha-256:")) {
+            throw Fields.syntax();
+        }
+        Fields.base64url(s.substring("sha-256:".length()), 32);
+    }
+
+    private static void cap(int bytes, int max) {
+        if (bytes > max) {
+            throw new RejectException(DiagnosticCode.E_SCHEMA_FIELD_LENGTH);
+        }
+    }
+}

src/main/java/org/entangled/schema/Closed.java

@@ -0,0 +1,54 @@
+package org.entangled.schema;
+
+import java.util.Set;
+import org.entangled.DiagnosticCode;
+import org.entangled.RejectException;
+import org.entangled.json.JsonValue;
+
+/**
+ * Closed-schema discipline for a single object level (section 02).
+ *
+ * <p>Given the permitted key set (required plus optional) and the required key
+ * set for an object, this verifies:
+ * <ul>
+ *   <li>every present key is permitted, else {@code E_SCHEMA_UNKNOWN_FIELD};</li>
+ *   <li>every required key is present, else {@code E_SCHEMA_REQUIRED_FIELD};</li>
+ *   <li>no permitted present value is the JSON {@code null} literal, else
+ *       {@code E_SCHEMA_NULL_VALUE} (section 04 forbids {@code null} anywhere).</li>
+ * </ul>
+ *
+ * <p>Order: unknown-field detection runs first (a stray key is a closed-schema
+ * breach regardless of its value), then required-presence, then the null check
+ * on the permitted values at this level. Nested objects run their own
+ * {@code Closed} check, so a {@code null} at any depth is caught at its level.
+ */
+public final class Closed {
+
+    private Closed() {
+    }
+
+    public static void check(JsonValue.Obj obj, Set<String> permitted, Set<String> required) {
+        for (String key : obj.members().keySet()) {
+            if (!permitted.contains(key)) {
+                throw new RejectException(DiagnosticCode.E_SCHEMA_UNKNOWN_FIELD);
+            }
+        }
+        for (String key : required) {
+            if (!obj.members().containsKey(key)) {
+                throw new RejectException(DiagnosticCode.E_SCHEMA_REQUIRED_FIELD);
+            }
+        }
+        for (JsonValue value : obj.members().values()) {
+            if (value instanceof JsonValue.Null) {
+                throw new RejectException(DiagnosticCode.E_SCHEMA_NULL_VALUE);
+            }
+        }
+    }
+
+    /** Convenience: a value that must not be the null literal at this position. */
+    public static void notNull(JsonValue value) {
+        if (value instanceof JsonValue.Null) {
+            throw new RejectException(DiagnosticCode.E_SCHEMA_NULL_VALUE);
+        }
+    }
+}