@arkiv-network/sdk 0.8.1-dev.1 → 0.9.0-next.2

package/dist/{attr-tmyREHtw.js → schema-DY4sqehl.js}

@@ -1,6 +1,6 @@
-import { bytesToString, checksumAddress, hexToBytes, isAddress, isHex, pad, stringToBytes, toHex } from "viem";
+import { checksumAddress, isAddress, isHex, pad, stringToBytes, toHex } from "viem";
 
-//#region src/attr/errors.ts
+//#region src/schema/errors.ts
 /**
 * A value was rejected by its tagged constructor — out of range, wrong length, bad checksum, too
 * much precision, and so on.
@@ -22,13 +22,13 @@ var InvalidValueError = class extends Error {
 };
 /**
 * A bare JavaScript value could not be given a type. Raised when an attribute or predicate is
-* handed something that is neither a tagged value nor one of the four bare forms
-* (`boolean`, `number`, `bigint`, `string`).
+* handed something that is neither a tagged value nor one of the five bare forms
+* (`boolean`, `number`, `bigint`, `string`, `Uint8Array`).
 */
 var UntypedValueError = class extends Error {
 	input;
 	constructor(input) {
-		super(`Cannot infer an Arkiv type for ${describe(input)}. Attribute values must be a tagged value (i32, u64, u256, dec, str, addr, key, bytes32, bool) or a bare boolean, number, bigint or string.`);
+		super(`Cannot infer an Arkiv type for ${describe(input)}. Attribute values must be a tagged value (i32, u64, u256, dec, str, addr, key, bytes32, bytes, bool) or a bare boolean, number, bigint, string or Uint8Array.`);
 		this.name = "UntypedValueError";
 		this.input = input;
 	}
@@ -37,15 +37,19 @@ var UntypedValueError = class extends Error {
 * An attribute was given `undefined` or `null` as its value.
 *
 * There is no such thing as an attribute with no value: an attribute either exists with a type, or
-* is not set. The fix is always to leave the name out of the map rather than to write an empty
-* value, so this is called out separately from {@link UntypedValueError} — the remedy is different.
+* is not set. The fix is always to leave the name out rather than to write an empty value — or, to
+* remove a column from an existing entity, to `unset` it in a patch — so this is called out
+* separately from {@link UntypedValueError}: the remedy is different.
+*
+* `createEntity` and `patchEntity` already treat a column given as `undefined` as left out, so
+* through them only `null` raises this.
 */
 var MissingValueError = class extends Error {
 	/** The attribute whose value was missing, when raised from an attribute map. */
 	attributeName;
 	constructor(input, attributeName) {
 		const subject = attributeName ? `attribute "${attributeName}"` : "attribute value";
-		super(`The ${subject} is ${input === null ? "null" : "undefined"}. An attribute is either set with a value and a type or not set at all, so there is nothing to write here. ` + (attributeName ? `Omit "${attributeName}" from the attributes instead — e.g. build the map conditionally, or drop the key when the value is absent.` : "Omit the attribute instead of giving it an empty value."));
+		super(`The ${subject} is ${input === null ? "null" : "undefined"}. An attribute is either set with a value and a type or not set at all, so there is nothing to write here. ` + (attributeName ? `Leave "${attributeName}" out of the values (or a patch's "set") instead — e.g. build the object conditionally, or drop the key when the value is absent. To remove the column from an existing entity, list it in a patch's "unset".` : "Omit the attribute instead of giving it an empty value."));
 		this.name = "MissingValueError";
 		this.attributeName = attributeName;
 	}
@@ -70,13 +74,51 @@ var ConflictingMutationError = class extends Error {
 		this.attributeName = attributeName;
 	}
 };
-/** More attributes were supplied than an entity operation can carry. */
+/**
+* More attributes were supplied than an entity operation can carry — raised by `defineSchema` for a
+* schema with more columns than one create could write.
+*/
 var TooManyAttributesError = class extends Error {
-	constructor(count, max) {
-		super(`An entity may carry at most ${max} attributes, got ${count}.`);
+	/**
+	* @param tagged - Whether `count` includes a named schema's tag, which the message then calls out:
+	* the tag is not among the declared columns, so the count would otherwise look off by one.
+	*/
+	constructor(count, max, tagged = false) {
+		super(`An entity may carry at most ${max} attributes, got ${count}.` + (tagged ? ` A named schema's tag counts as one of them, so it may declare at most ${max - 1} columns.` : ""));
 		this.name = "TooManyAttributesError";
 	}
 };
+/** The `bytes` values of one create or patch add up to more than `MAX_ENTITY_BYTES`. */
+var EntityTooLargeError = class extends Error {
+	constructor(total, max) {
+		super(`The bytes columns of one create or patch may hold at most ${max} bytes in total, got ${total}. Split the data across entities, or store it elsewhere and keep a reference`);
+		this.name = "EntityTooLargeError";
+	}
+};
+/** A schema, or one of its columns, was defined in a way the SDK or the protocol cannot honour. */
+var SchemaDefinitionError = class extends Error {
+	/** The column at fault, when there is one. */
+	columnName;
+	constructor(reason, columnName) {
+		super(`Invalid schema${columnName === void 0 ? "" : ` column "${columnName}"`}: ${reason}.`);
+		this.name = "SchemaDefinitionError";
+		this.columnName = columnName;
+	}
+};
+/**
+* Data did not fit its schema: a write named a column the schema does not have, left out one it
+* requires, or gave one a value of the wrong type — or an entity read back through a schema lacks a
+* required column or holds one with a different type.
+*/
+var SchemaMismatchError = class extends Error {
+	/** The column at fault. */
+	columnName;
+	constructor(columnName, reason) {
+		super(`Column "${columnName}": ${reason}.`);
+		this.name = "SchemaMismatchError";
+		this.columnName = columnName;
+	}
+};
 /** The node sent back an attribute this SDK cannot decode. */
 var UnknownAttributeTypeError = class extends Error {
 	/** The type as the node named it — a tag over JSON-RPC, a typeId on the wire. */
@@ -106,7 +148,7 @@ function safeJson(input) {
 }
 
 //#endregion
-//#region src/attr/decimal.ts
+//#region src/schema/decimal.ts
 /**
 * Decimal places a `dec` value is scaled by. Fixed by the protocol, so any two decimals are
 * directly comparable — and range-indexable — as plain integers.
@@ -165,7 +207,7 @@ function unitsToDecimal(units) {
 }
 
 //#endregion
-//#region src/attr/types.ts
+//#region src/schema/types.ts
 /**
 * The protocol's attribute type vocabulary, mapping each short **tag** (the name used by the
 * client, the query language and this SDK) to its **typeId** (the byte carried on the wire and in
@@ -174,18 +216,20 @@ function unitsToDecimal(units) {
 * The typeIds are consensus-critical: they are written into entity records and mixed into index
 * keys, so this table must never drift from the node's `AttributeType`.
 *
-* | tag       | typeId | ABI wire type       | indexing          |
-* | --------- | ------ | ------------------- | ----------------- |
-* | `bool`    | 1      | `bool`              | equality          |
-* | `i32`     | 2      | `int32`             | equality + range  |
-* | `u64`     | 3      | `uint64`            | equality + range  |
-* | `u256`    | 4      | `uint256`           | equality + range  |
-* | `dec`     | 5      | `int256` (18 dp)    | equality + range  |
-* | `bytes32` | 6      | `bytes32`           | equality          |
-* | `bytes`   | 7      | `bytes`             | none — system-only |
-* | `str`     | 8      | `string` (<= 128 B) | equality + prefix |
-* | `addr`    | 9      | `address`           | equality          |
-* | `key`     | 10     | `bytes32`           | equality          |
+* | tag       | typeId | ABI wire type        | when indexed      |
+* | --------- | ------ | -------------------- | ----------------- |
+* | `bool`    | 1      | `bool`               | equality          |
+* | `i32`     | 2      | `int32`              | equality + range  |
+* | `u64`     | 3      | `uint64`             | equality + range  |
+* | `u256`    | 4      | `uint256`            | equality + range  |
+* | `dec`     | 5      | `int256` (18 dp)     | equality + range  |
+* | `bytes32` | 6      | `bytes32`            | equality          |
+* | `bytes`   | 7      | `bytes` (<= 128 KiB) | never indexed     |
+* | `str`     | 8      | `string` (<= 128 B)  | equality + prefix |
+* | `addr`    | 9      | `address`            | equality          |
+* | `key`     | 10     | `bytes32`            | equality          |
+*
+* On the wire the typeId shares its byte with the indexed flag — see {@link INDEXED_FLAG}.
 */
 const TYPE_IDS = {
 	bool: 1,
@@ -200,6 +244,15 @@ const TYPE_IDS = {
 	key: 10
 };
 /**
+* Bit 7 of the `typeId` byte: set when the node should index the attribute. The low seven bits are
+* the type itself, so `str` travels as `8` unindexed and `0x88` indexed.
+*/
+const INDEXED_FLAG = 128;
+/** Whether attributes of this type may be indexed — everything except `bytes`. */
+function isIndexable(tag) {
+	return tag !== "bytes";
+}
+/**
 * Builds a validated value. Module-internal: the constructors in `values.ts` call this **after**
 * validating, which is what makes the {@link validated} brand meaningful.
 */
@@ -217,7 +270,57 @@ function isArkivValue(input) {
 }
 
 //#endregion
-//#region src/attr/values.ts
+//#region src/schema/column.ts
+/**
+* Marks a column. A registry symbol rather than `instanceof`, so a column made by one copy of the
+* SDK — its ESM build, say — is still recognised by another, such as the CJS build a dependency
+* loaded.
+*/
+const COLUMN_BRAND = Symbol.for("@arkiv-network/sdk/column");
+var ColumnDefinition = class ColumnDefinition {
+	type;
+	isIndexed;
+	isOptional;
+	defaultValue;
+	#coerce;
+	constructor(type, isIndexed, isOptional, defaultValue, coerce) {
+		this.type = type;
+		this.isIndexed = isIndexed;
+		this.isOptional = isOptional;
+		this.defaultValue = defaultValue;
+		this.#coerce = coerce;
+		Object.defineProperty(this, COLUMN_BRAND, { value: true });
+		Object.freeze(this);
+	}
+	indexed() {
+		if (this.type === "bytes") throw new SchemaDefinitionError("a bytes column cannot be indexed. Bytes are stored, never indexed, so they can be selected but not filtered on — index a str, bytes32 or key derived from them instead");
+		return this.#with({ isIndexed: true });
+	}
+	optional() {
+		return this.#with({ isOptional: true });
+	}
+	default(...args) {
+		if (args.length === 0) throw new SchemaDefinitionError(`.default() needs a value — e.g. ${this.type}().default(...). Leave .default() off for a column the create must always provide`);
+		return this.#with({ defaultValue: this.#coerce(this.type, args[0]) });
+	}
+	#with(changes) {
+		return new ColumnDefinition(this.type, changes.isIndexed ?? this.isIndexed, changes.isOptional ?? this.isOptional, changes.defaultValue ?? this.defaultValue, this.#coerce);
+	}
+};
+/**
+* A fresh column of type `tag`: unindexed, required, no default. Internal seam for the type
+* constructors, which return one when called with no arguments.
+*/
+function createColumn(tag, coerce) {
+	return new ColumnDefinition(tag, false, false, void 0, coerce);
+}
+/** Whether `input` is a column, as opposed to a value or anything else. */
+function isColumn(input) {
+	return typeof input === "object" && input !== null && COLUMN_BRAND in input;
+}
+
+//#endregion
+//#region src/schema/values.ts
 /** The widest `i32`. */
 const I32_MAX = 2147483647;
 /** The narrowest `i32`. */
@@ -231,6 +334,11 @@ const U256_MAX = 2n ** 256n - 1n;
 */
 const MAX_STRING_BYTES = 128;
 /**
+* The longest `bytes` value, in bytes. The cap applies to each `bytes` attribute separately, but
+* all the `bytes` values of one create or patch also share the `MAX_ENTITY_BYTES` budget.
+*/
+const MAX_BYTES_LENGTH = 128 * 1024;
+/**
 * Finds the first C0 control or DEL — the characters a `str` may not contain.
 */
 function findControlChar(value) {
@@ -242,31 +350,15 @@ function findControlChar(value) {
 		};
 	}
 }
-/**
-* A boolean.
-*
-* `bool` is the one type that may also be written bare — `{ flagged: true }` and
-* `{ flagged: bool(true) }` are the same attribute.
-*
-* @example
-* bool(true) // { type: "bool", value: true }
-*/
-function bool(value) {
+function bool(...args) {
+	if (args.length === 0) return createColumn("bool", toTypedValue);
+	const [value] = args;
 	if (typeof value !== "boolean") throw new InvalidValueError("bool", value, "not a boolean");
 	return makeValue("bool", value);
 }
-/**
-* A 32-bit signed integer, indexed for equality and range queries. This is the default type for a
-* bare number, so `{ level: 10 }` and `{ level: i32(10) }` are the same attribute.
-*
-* @param value - An integer in [-2147483648, 2147483647].
-* @throws {InvalidValueError} If the value is not an integer, or does not fit an `i32`.
-*
-* @example
-* i32(10)   // { type: "i32", value: 10 }
-* i32(-42)  // negative values are fine — i32 is the signed integer
-*/
-function i32(value) {
+function i32(...args) {
+	if (args.length === 0) return createColumn("i32", toTypedValue);
+	const [value] = args;
 	if (typeof value === "bigint") {
 		if (value > BigInt(I32_MAX) || value < BigInt(I32_MIN)) throw new InvalidValueError("i32", value, outOfI32Range(value >= 0n));
 		return makeValue("i32", Number(value));
@@ -280,41 +372,13 @@ function outOfI32Range(nonNegative) {
 	const range = `outside the i32 range [${I32_MIN}, ${I32_MAX}]`;
 	return nonNegative ? `${range} — use u64(...) for large counters, timestamps and block heights (Date.now() does not fit an i32), or u256(...) beyond 2**64 - 1` : `${range} — use dec(...) for values that need more range than an i32`;
 }
-/**
-* A 256-bit unsigned integer, indexed for equality and range queries. The type for token amounts
-* and anything else that can outgrow 2⁶⁴ — reach for {@link u64} first for counters, timestamps
-* and block heights.
-*
-* @param value - A non-negative integer, as a `bigint`, a safe `number`, or a decimal or `0x` hex
-* string.
-* @throws {InvalidValueError} If the value is negative, non-integral, or wider than 256 bits.
-*
-* @example
-* u256(1_000_000n)
-* u256(Date.now())        // safe integers are accepted
-* u256("0xf4240")         // hex, as it comes back over JSON-RPC
-*/
-function u256(value) {
-	return makeValue("u256", toUnsigned("u256", value, U256_MAX));
+function u256(...args) {
+	if (args.length === 0) return createColumn("u256", toTypedValue);
+	return makeValue("u256", toUnsigned("u256", args[0], U256_MAX));
 }
-/**
-* A 64-bit unsigned integer, indexed for equality and range queries.
-*
-* This is the width the protocol counts in: block heights, `$expiresAt` and the entity-nonce are
-* all `u64`, so it is the type to reach for when a value has to line up with one of them. Use
-* {@link u256} for token amounts and anything else that can exceed 2⁶⁴.
-*
-* @param value - A non-negative integer, as a `bigint`, a safe `number`, or a decimal or `0x` hex
-* string.
-* @throws {InvalidValueError} If the value is negative, non-integral, or wider than 64 bits.
-*
-* @example
-* u64(1_200_000n)     // a block height
-* u64(Date.now())     // safe integers are accepted
-* u64("0x124f80")     // hex, as it comes back over JSON-RPC
-*/
-function u64(value) {
-	return makeValue("u64", toUnsigned("u64", value, U64_MAX));
+function u64(...args) {
+	if (args.length === 0) return createColumn("u64", toTypedValue);
+	return makeValue("u64", toUnsigned("u64", args[0], U64_MAX));
 }
 /**
 * Parses and range-checks an unsigned integer for `tag`, whose widest value is `max`.
@@ -341,25 +405,9 @@ function toUnsignedBigint(tag, value) {
 	}
 	throw new InvalidValueError(tag, value, "not a bigint, number or string");
 }
-/**
-* A signed fixed-point decimal with exactly 18 decimal places, indexed for equality and range
-* queries.
-*
-* Pass fractional values as **strings**. A JavaScript number cannot represent most decimals
-* exactly, so accepting `dec(0.1 + 0.2)` would quietly store `0.30000000000000004`; requiring the
-* string keeps what you write and what is stored the same thing. Excess precision is likewise an
-* error rather than a rounding.
-*
-* @param value - A decimal string, or an integral `number` / `bigint`.
-* @throws {InvalidValueError} If the value is malformed, has more than 18 fractional digits, or
-* falls outside the `int256` range.
-*
-* @example
-* dec("3.5")
-* dec("-0.000000000000000001")  // the smallest step
-* dec(5)                        // integers may be passed bare
-*/
-function dec(value) {
+function dec(...args) {
+	if (args.length === 0) return createColumn("dec", toTypedValue);
+	const [value] = args;
 	if (typeof value === "string") return makeValue("dec", unitsToDecimal(decimalToUnits(value)));
 	if (typeof value === "bigint") return decFromUnits(value * DECIMAL_UNIT);
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new InvalidValueError("dec", value, "not a number");
@@ -386,75 +434,39 @@ function decUnits(value) {
 function decFromUnits(units) {
 	return makeValue("dec", unitsToDecimal(units));
 }
-/**
-* A UTF-8 string of at most 128 bytes, indexed for equality and prefix (`STARTSWITH`) matching.
-*
-* The limit is on **bytes**, not characters: a string of 128 emoji does not fit.
-*
-* C0 control characters and DEL are rejected: the query language writes a `str` as `str('...')`,
-* whose only escape is a doubled quote, so a control character could be stored but never queried.
-*
-* @throws {InvalidValueError} If the value is not a string, holds a control character, or exceeds
-* 128 UTF-8 bytes.
-*
-* @example
-* str("Bob")
-*/
-function str(value) {
+function str(...args) {
+	if (args.length === 0) return createColumn("str", toTypedValue);
+	const [value] = args;
 	if (typeof value !== "string") throw new InvalidValueError("str", value, "not a string");
 	const control = findControlChar(value);
-	if (control !== void 0) throw new InvalidValueError("str", value, `contains the control character U+${control.code.toString(16).padStart(4, "0").toUpperCase()} at index ${control.index}`, "A str is written into a query as str('...'), whose only escape is a doubled quote — there is no spelling for a control character, so this value could be stored but never queried. Free-form text belongs in the entity payload; keep a short, printable key here.");
-	const bytes = stringToBytes(value).length;
-	if (bytes > MAX_STRING_BYTES) throw new InvalidValueError("str", value, `${bytes} UTF-8 bytes exceeds the ${MAX_STRING_BYTES}-byte limit on a str`, "Store the long form in the entity payload and keep a short, queryable key here.");
+	if (control !== void 0) throw new InvalidValueError("str", value, `contains the control character U+${control.code.toString(16).padStart(4, "0").toUpperCase()} at index ${control.index}`, "A str is written into a query as str('...'), whose only escape is a doubled quote — there is no spelling for a control character, so this value could be stored but never queried. Free-form text belongs in a bytes column; keep a short, printable key here.");
+	const bytes$1 = stringToBytes(value).length;
+	if (bytes$1 > MAX_STRING_BYTES) throw new InvalidValueError("str", value, `${bytes$1} UTF-8 bytes exceeds the ${MAX_STRING_BYTES}-byte limit on a str`, "Store the long form in a bytes column and keep a short, queryable key here.");
 	return makeValue("str", value);
 }
-/**
-* A 20-byte Ethereum address, indexed for equality.
-*
-* All-lowercase and all-uppercase input carries no checksum and is accepted as-is; mixed-case
-* input is checked against its EIP-55 checksum, so a mistyped address is caught here rather than
-* being written to a wrong account. The stored value is always EIP-55 checksummed.
-*
-* @throws {InvalidValueError} If the value is not 20 hex bytes, or fails its EIP-55 checksum.
-*
-* @example
-* addr("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
-*/
-function addr(value) {
+function addr(...args) {
+	if (args.length === 0) return createColumn("addr", toTypedValue);
+	const [value] = args;
 	if (typeof value !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(value)) throw new InvalidValueError("addr", value, "not a 20-byte 0x-prefixed hex address");
 	const body = value.slice(2);
 	if (body !== body.toLowerCase() && body !== body.toUpperCase() && !isAddress(value, { strict: true })) throw new InvalidValueError("addr", value, "fails its EIP-55 checksum, so a digit is probably mistyped", `If those hex digits are right, the correctly checksummed form is ${checksumAddress(value)}.`);
 	return makeValue("addr", checksumAddress(value));
 }
-/**
-* A reference to another entity, indexed for equality.
-*
-* References are **weak**: nothing checks that the target exists when you write it, and a
-* reference to a deleted or expired entity is allowed to dangle.
-*
-* @param value - A 32-byte entity key, as `0x` hex or raw bytes.
-* @throws {InvalidValueError} If the value is not exactly 32 bytes.
-*
-* @example
-* key(parentEntityKey)
-*/
-function key(value) {
-	return makeValue("key", asFixedHex("key", value, 32));
+function key(...args) {
+	if (args.length === 0) return createColumn("key", toTypedValue);
+	return makeValue("key", asFixedHex("key", args[0], 32));
 }
-/**
-* 32 opaque bytes — a hash, a digest, an identifier from another system — indexed for equality.
-*
-* Use {@link key} instead when the bytes are an Arkiv entity key: same wire width, but the
-* distinct type makes the reference visible to readers and to the query language.
-*
-* @param value - 32 bytes, as `0x` hex or raw bytes.
-* @throws {InvalidValueError} If the value is not exactly 32 bytes.
-*
-* @example
-* bytes32(keccak256(toBytes("hello")))
-*/
-function bytes32(value) {
-	return makeValue("bytes32", asFixedHex("bytes32", value, 32));
+function bytes32(...args) {
+	if (args.length === 0) return createColumn("bytes32", toTypedValue);
+	return makeValue("bytes32", asFixedHex("bytes32", args[0], 32));
+}
+function bytes(...args) {
+	if (args.length === 0) return createColumn("bytes", toTypedValue);
+	const [value] = args;
+	const hex = asHex("bytes", value);
+	const length = (hex.length - 2) / 2;
+	if (length > MAX_BYTES_LENGTH) throw new InvalidValueError("bytes", `<${length} bytes>`, `${length} bytes exceeds the ${MAX_BYTES_LENGTH}-byte limit on a bytes value`, "Split it across several entities, or store the bulk elsewhere and keep a reference.");
+	return makeValue("bytes", hex);
 }
 /** Normalizes hex-or-bytes input of a known width into lowercase `0x` hex. */
 function asFixedHex(tag, value, size$1) {
@@ -462,8 +474,15 @@ function asFixedHex(tag, value, size$1) {
 		if (value.length !== size$1) throw new InvalidValueError(tag, `<${value.length} bytes>`, `not exactly ${size$1} bytes`);
 		return toHex(value);
 	}
+	const hex = asHex(tag, value);
+	if (hex.length !== 2 + size$1 * 2) throw new InvalidValueError(tag, value, `${(hex.length - 2) / 2} bytes, not exactly ${size$1} bytes`);
+	return hex;
+}
+/** Normalizes hex-or-bytes input into lowercase `0x` hex of a whole number of bytes. */
+function asHex(tag, value) {
+	if (value instanceof Uint8Array) return toHex(value);
 	if (typeof value !== "string" || !isHex(value, { strict: true })) throw new InvalidValueError(tag, value, "not 0x-prefixed hex");
-	if (value.length !== 2 + size$1 * 2) throw new InvalidValueError(tag, value, `${(value.length - 2) / 2} bytes, not exactly ${size$1} bytes`);
+	if (value.length % 2 !== 0) throw new InvalidValueError(tag, value, "an odd number of hex digits, so not whole bytes");
 	return value.toLowerCase();
 }
 /**
@@ -475,8 +494,8 @@ function asFixedHex(tag, value, size$1) {
 *
 * @throws {MissingValueError} If the input is `undefined` or `null` — an attribute is either set
 * with a value and a type, or not set at all.
-* @throws {UntypedValueError} If the input is not a tagged value or a bare boolean, number, bigint
-* or string.
+* @throws {UntypedValueError} If the input is not a tagged value or a bare boolean, number, bigint,
+* string or `Uint8Array`.
 * @throws {InvalidValueError} If a bare value does not fit the type it defaults to.
 *
 * @example
@@ -493,16 +512,47 @@ function toValue(input, attributeName) {
 		case "bigint": return u256(input);
 		case "string": return str(input);
 		default: {
+			if (input instanceof Uint8Array) return bytes(input);
+			if (isArkivValue(input)) return revalidate(input);
 			const candidate = input;
-			if (isArkivValue(candidate)) {
-				if (candidate.type === "bytes") throw new InvalidValueError("bytes", candidate.value, "system-only — bytes backs the entity payload and cannot be set as an attribute", "Pass the bytes as the entity payload instead.");
-				return revalidate(candidate);
-			}
+			if (isColumn(candidate)) throw columnGivenAsValue(candidate);
 			throw new UntypedValueError(input);
 		}
 	}
 }
 /**
+* Resolves `input` to a value of type `tag` — a tagged value of that type, or whatever `tag`'s
+* constructor accepts. What a column's `.default(...)` runs its argument through.
+*
+* @throws {InvalidValueError} If the input does not make a valid value of type `tag`.
+*/
+function toTypedValue(tag, input) {
+	if (isArkivValue(input)) {
+		const value = revalidate(input);
+		if (value.type !== tag) throw new InvalidValueError(tag, input, `a ${value.type} value, not a ${tag}`);
+		return value;
+	}
+	if (isColumn(input)) throw columnGivenAsValue(input);
+	const construct = CONSTRUCTORS[tag];
+	return construct(input);
+}
+function columnGivenAsValue(column) {
+	return new InvalidValueError(column.type, `<${column.type} column>`, "a column, not a value", `Pass the value itself, e.g. ${column.type}(...) with an argument — ${column.type}() with none declares a schema column.`);
+}
+/** Each tag's constructor, called with a value. */
+const CONSTRUCTORS = {
+	bool,
+	i32,
+	u64,
+	u256,
+	dec,
+	bytes32,
+	bytes,
+	str,
+	addr,
+	key
+};
+/**
 * Re-runs a tagged value through its own constructor.
 *
 * {@link isArkivValue} can only check shape — the `validated` brand is a type-level construct with
@@ -523,6 +573,7 @@ function revalidate(value) {
 		case "u256": return u256(value.value);
 		case "dec": return dec(value.value);
 		case "bytes32": return bytes32(value.value);
+		case "bytes": return bytes(value.value);
 		case "str": return str(value.value);
 		case "addr": return addr(value.value);
 		case "key": return key(value.value);
@@ -530,7 +581,7 @@ function revalidate(value) {
 }
 
 //#endregion
-//#region src/attr/codec.ts
+//#region src/schema/codec.ts
 function strFromChain(value) {
 	return makeValue("str", value);
 }
@@ -565,16 +616,33 @@ function encodeValueBytes(value) {
 /**
 * Encodes a named, typed attribute into its ABI form.
 *
-* @param name - The attribute name. Assumed already validated, or a system (`$`) name the SDK sets
-* itself.
+* @param name - The attribute name. Assumed already validated.
+* @param indexed - Whether the node should index it. Never true for `bytes`, which the engine
+* rejects with the flag set.
+* @throws {InvalidValueError} If asked to index a `bytes` value.
 */
-function encodeAbiAttribute(name, value) {
+function encodeAbiAttribute(name, value, indexed) {
+	if (indexed && value.type === "bytes") throw new InvalidValueError("bytes", `<${name}>`, "bytes are stored, never indexed");
 	return {
 		name: toHex(name, { size: 32 }),
-		typeId: TYPE_IDS[value.type],
+		typeId: TYPE_IDS[value.type] | (indexed ? INDEXED_FLAG : 0),
 		value: encodeValueBytes(value)
 	};
 }
+/**
+* Splits a wire `typeId` into its type and indexed flag.
+*
+* @throws {UnknownAttributeTypeError} If the low seven bits name no known type.
+*/
+function decodeTypeId(typeId) {
+	const base = typeId & ~INDEXED_FLAG;
+	const tag = Object.keys(TYPE_IDS).find((candidate) => TYPE_IDS[candidate] === base);
+	if (tag === void 0) throw new UnknownAttributeTypeError(typeId);
+	return {
+		tag,
+		indexed: (typeId & INDEXED_FLAG) !== 0
+	};
+}
 /** Encodes a tombstone — the mutation that unsets `name`. Legal only in a patch. */
 function encodeTombstone(name) {
 	return {
@@ -644,7 +712,7 @@ function asIntegerish(tag, value) {
 }
 
 //#endregion
-//#region src/attr/names.ts
+//#region src/schema/names.ts
 /** The longest attribute name, in bytes — the width of the on-chain `Ident32` name cell. */
 const MAX_NAME_BYTES = 32;
 /**
@@ -670,6 +738,7 @@ const RESERVED = new Set([
 	"not",
 	"true",
 	"false",
+	"between",
 	"startswith",
 	"exists",
 	"typeof",
@@ -689,8 +758,9 @@ const RESERVED = new Set([
 * reserved words.
 *
 * @param name - The attribute name.
-* @throws {InvalidAttributeNameError} If the name is empty, too long, uses characters outside the
-* grammar, or collides with a reserved word.
+* @throws {InvalidAttributeNameError} If the name is empty, starts with `$` (reserved for system
+* attributes), too long, uses characters outside the grammar, contains `--` (which opens a query
+* comment), or collides with a reserved word.
 */
 function validateAttributeName(name) {
 	if (typeof name !== "string" || name.length === 0) throw new InvalidAttributeNameError(String(name), "the name is empty");
@@ -715,89 +785,208 @@ function isValidAttributeName(name) {
 }
 
 //#endregion
-//#region src/attr/attributes.ts
+//#region src/schema/schema.ts
 /**
-* The most attribute cells one operation may carry.
+* The most attributes one entity operation may carry, and so the most columns a schema may have —
+* one fewer for a named schema, whose tag is one more attribute on every create.
 */
 const MAX_ATTRIBUTES = 32;
 /**
-* The largest payload an entity may carry, in bytes. The payload travels as the `$payload` system
-* cell, so this is a bound on that one attribute rather than on the operation as a whole.
+* The attribute a named schema tags its entities with: an indexed `str` holding the schema's name.
+* Creates write it, and `.from(schema)` filters on it, so a query through a schema only ever sees
+* entities written through it.
+*/
+const SCHEMA_ATTRIBUTE = "arkiv.schema";
+/**
+* Marks a schema. A registry symbol rather than `instanceof`, so a schema defined through one copy
+* of the SDK — its CJS build, say — is still recognised by another, such as the ESM build an app
+* loaded.
 */
-const MAX_PAYLOAD_BYTES = 128 * 1024;
-/** The system attribute holding an entity's opaque payload. */
-const PAYLOAD_CELL = "$payload";
-/** The system attribute holding an entity's content type. */
-const CONTENT_TYPE_CELL = "$contentType";
+const SCHEMA_BRAND = Symbol.for("@arkiv-network/sdk/schema");
 /**
-* The typed form of an attribute map: names validated, bare values resolved to their default type.
+* A schema: the named, typed attributes an entity of one kind carries, and which of them the node
+* indexes. Built with {@link defineSchema}.
 *
-* @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
-* @throws {MissingValueError} If a value is `undefined` or `null` — omit the name instead.
-* @throws {InvalidValueError} If a value does not fit the type it names or defaults to.
-* @throws {TooManyAttributesError} If there are more than {@link MAX_ATTRIBUTES} attributes.
+* A schema is an SDK-side convention. The node sees only attributes, each with a type and an
+* indexed flag; the schema is what types the SDK's writes and reads, and checks them at runtime.
 *
-* @example
-* resolveAttributes({ level: 10, name: "Bob" })
-* // { level: { type: "i32", value: 10 }, name: { type: "str", value: "Bob" } }
-*/
-function resolveAttributes(attributes) {
-	const entries = Object.entries(attributes);
-	if (entries.length > MAX_ATTRIBUTES) throw new TooManyAttributesError(entries.length, MAX_ATTRIBUTES);
-	const resolved = {};
-	for (const [name, input] of entries) {
+* A named schema also tags every entity it creates with its name, in the indexed
+* {@link SCHEMA_ATTRIBUTE} attribute, so that a query through it sees only its own entities.
+*
+* @typeParam C - The columns, keyed by attribute name.
+*/
+var Schema = class {
+	/** The name entities are tagged with, or `undefined` for an untagged schema. */
+	name;
+	/** The columns, keyed by attribute name, in the order they were declared. */
+	columns;
+	/** The tag every create writes and every query filters on, if the schema is named. */
+	tag;
+	/** Use {@link defineSchema}. */
+	constructor(name, columns) {
+		this.tag = name === void 0 ? void 0 : validateName(name);
+		validateColumns(columns, name !== void 0);
+		this.name = name;
+		this.columns = Object.freeze({ ...columns });
+		Object.defineProperty(this, SCHEMA_BRAND, { value: true });
+		Object.freeze(this);
+	}
+};
+function defineSchema(...args) {
+	return args.length === 2 ? new Schema(args[0], args[1]) : new Schema(void 0, args[0]);
+}
+function validateName(name) {
+	if (typeof name !== "string" || name.length === 0) throw new SchemaDefinitionError("a schema name must be a non-empty string — leave it out for an untagged schema");
+	try {
+		return str(name);
+	} catch (error) {
+		if (!(error instanceof InvalidValueError)) throw error;
+		throw new SchemaDefinitionError(`the name is not a valid str tag. ${error.message}`);
+	}
+}
+function validateColumns(columns, tagged) {
+	if (typeof columns !== "object" || columns === null || Array.isArray(columns)) throw new SchemaDefinitionError("defineSchema takes an object of columns keyed by name");
+	const entries = Object.entries(columns);
+	const attributes = entries.length + (tagged ? 1 : 0);
+	if (attributes > MAX_ATTRIBUTES) throw new TooManyAttributesError(attributes, MAX_ATTRIBUTES, tagged);
+	for (const [name, column] of entries) {
 		validateAttributeName(name);
-		resolved[name] = toValue(input, name);
+		if (name === SCHEMA_ATTRIBUTE) throw new SchemaDefinitionError(`"${name}" is the attribute a named schema tags its entities with, so a column cannot use it. Pick another name`, name);
+		if (!isColumn(column)) throw notAColumn(name, column);
 	}
-	return resolved;
+}
+/** Whether `input` is a schema built with {@link defineSchema}. */
+function isSchema(input) {
+	return typeof input === "object" && input !== null && SCHEMA_BRAND in input;
 }
 /**
-* Encodes an attribute map, plus the payload and content-type system cells, into the ABI attribute
-* array an operation carries.
+* The column `name` of `schema`, or `undefined` if it has none. Only the schema's own columns
+* count, so an inherited key such as `toString` or `__proto__` is not mistaken for one.
+*/
+function lookupColumn(schema, name) {
+	return Object.hasOwn(schema.columns, name) ? schema.columns[name] : void 0;
+}
+/** The schema's column names, for an error message that has to say what would have worked. */
+function describeColumns(schema) {
+	return Object.keys(schema.columns).join(", ") || "(none)";
+}
+function notAColumn(name, input) {
+	if (isArkivValue(input)) return new SchemaDefinitionError(`got a ${input.type} value where a column belongs. Did you mean ${input.type}().default(${defaultArgument(input)})? Called with a value, ${input.type}(...) makes a value; called with none, ${input.type}() declares a column`, name);
+	return new SchemaDefinitionError("not a column. Declare it with a type constructor called with no arguments, e.g. str() or dec().indexed()", name);
+}
+/** A value spelled as the argument its constructor would take, for an error message. */
+function defaultArgument(value) {
+	switch (value.type) {
+		case "bool":
+		case "i32": return String(value.value);
+		case "u64":
+		case "u256": return `${value.value}n`;
+		default: return JSON.stringify(value.value);
+	}
+}
+
+//#endregion
+//#region src/schema/attributes.ts
+/**
+* The most data the `bytes` columns of one create or patch may hold together, in bytes. Each
+* `bytes` value is also capped on its own, at `MAX_BYTES_LENGTH`.
 *
-* @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
-* @throws {MissingValueError} If a value is `undefined` or `null`.
-* @throws {InvalidValueError} If a value does not fit its type.
-* @throws {TooManyAttributesError} If there are more than {@link MAX_ATTRIBUTES} attributes.
+* Provisional: the protocol has not settled a per-entity cap yet, so this keeps the budget the
+* single payload had — and an operation much larger than it would not fit in a transaction the
+* node accepts anyway.
 */
-function encodeAttributes(attributes = {}, system = {}) {
-	const cells = Object.entries(resolveAttributes(attributes));
-	if (system.payload !== void 0) {
-		if (system.payload.length > MAX_PAYLOAD_BYTES) throw new InvalidValueError("bytes", `<${system.payload.length} bytes>`, `${system.payload.length} bytes exceeds the ${MAX_PAYLOAD_BYTES}-byte payload limit`, "Store the bulk elsewhere and keep a reference to it on the entity.");
-		cells.push([PAYLOAD_CELL, makeValue("bytes", toHexBytes(system.payload))]);
+const MAX_ENTITY_BYTES = 128 * 1024;
+/**
+* Encodes a create's values into the ABI attribute array it carries: every column the
+* values name, plus the default of every defaulted column they leave out, each flagged indexed or
+* not as its column says — and, for a named schema, the indexed tag that marks the entity as its.
+*
+* @throws {SchemaDefinitionError} If `schema` is not a schema built with `defineSchema`.
+* @throws {TypeError} If `values` is not an object.
+* @throws {SchemaMismatchError} If a value names a column the schema lacks, a required column is
+* left out, or a value's type is not its column's.
+* @throws {MissingValueError} If a value is `null`.
+* @throws {UntypedValueError} If a value is neither a tagged value nor a bare form.
+* @throws {InvalidValueError} If a value does not fit its type.
+* @throws {EntityTooLargeError} If the `bytes` values add up to more than {@link MAX_ENTITY_BYTES}.
+*/
+function encodeCreate(schema, values) {
+	assertSchema(schema);
+	for (const name of keysOf(values, "create")) columnFor(schema, name, "create");
+	const attributes = [];
+	if (schema.tag !== void 0) attributes.push(encodeAbiAttribute(SCHEMA_ATTRIBUTE, schema.tag, true));
+	for (const [name, column] of Object.entries(schema.columns)) {
+		const input = Object.hasOwn(values, name) ? values[name] : void 0;
+		if (input === void 0) {
+			if (column.defaultValue !== void 0) attributes.push(encodeAbiAttribute(name, column.defaultValue, column.isIndexed));
+			else if (!column.isOptional) throw new SchemaMismatchError(name, `the create leaves out a required ${column.type} column. Give it a value, or declare it ${column.type}().optional() or with a .default(...)`);
+			continue;
+		}
+		attributes.push(encodeColumn(name, column, input));
 	}
-	if (system.contentType !== void 0) cells.push([CONTENT_TYPE_CELL, str(system.contentType)]);
-	if (cells.length > MAX_ATTRIBUTES) throw new TooManyAttributesError(cells.length, MAX_ATTRIBUTES);
-	return cells.map(([name, value]) => encodeAbiAttribute(name, value)).sort(byName);
+	assertBytesFit(attributes);
+	return attributes.sort(byName);
 }
 /**
-* Encodes a patch's mutations into the ABI attribute array the operation carries.
+* Encodes a patch into the ABI attribute array it carries: a write for each column in `set`, with
+* the indexed flag its column declares, and a tombstone for each name in `unset`. A column `set`
+* to `undefined` is left out, as it is from a create.
 *
+* Writing a column with a different indexed flag than the entity holds flips its indexing, so a
+* schema that marks a column `.indexed()` indexes it from the next patch that writes it.
+*
+* @throws {SchemaDefinitionError} If `schema` is not a schema built with `defineSchema`.
+* @throws {SchemaMismatchError} If a name is not a column, a value's type is not its column's, or
+* `unset` names a required column.
 * @throws {ConflictingMutationError} If a name appears in both `set` and `unset`.
-* @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
-* @throws {MissingValueError} If a value is `undefined` or `null`.
+* @throws {MissingValueError} If a value in `set` is `null`.
+* @throws {UntypedValueError} If a value in `set` is neither a tagged value nor a bare form.
 * @throws {InvalidValueError} If a value does not fit its type.
-* @throws {TooManyAttributesError} If the mutations exceed {@link MAX_ATTRIBUTES}.
-* @throws {TypeError} If `unset` is not an array.
-*/
-function encodeMutations({ set, unset, payload, contentType }) {
-	const written = encodeAttributes(set, {
-		payload,
-		contentType
-	});
-	const tombstones = resolveUnset(unset, set).map(encodeTombstone);
-	const mutations = [...written, ...tombstones];
-	if (mutations.length > MAX_ATTRIBUTES) throw new TooManyAttributesError(mutations.length, MAX_ATTRIBUTES);
+* @throws {EntityTooLargeError} If the `bytes` values in `set` add up to more than
+* {@link MAX_ENTITY_BYTES}.
+* @throws {TypeError} If `set` is not an object, or `unset` is not an array.
+*/
+function encodePatch(schema, { set = {}, unset = [] }) {
+	assertSchema(schema);
+	const mutations = [];
+	for (const name of keysOf(set, "patch")) {
+		const column = columnFor(schema, name, "patch");
+		const input = set[name];
+		if (input !== void 0) mutations.push(encodeColumn(name, column, input));
+	}
+	if (!Array.isArray(unset)) throw new TypeError(`"unset" must be an array of column names`);
+	for (const name of new Set(unset)) {
+		const column = columnFor(schema, name, "patch");
+		if (!column.isOptional) throw new SchemaMismatchError(name, `a required column, so unsetting it would leave the entity without a value its schema requires. Declare it ${column.type}().optional() to allow that`);
+		if (Object.hasOwn(set, name) && set[name] !== void 0) throw new ConflictingMutationError(name);
+		mutations.push(encodeTombstone(name));
+	}
+	assertBytesFit(mutations);
 	return mutations.sort(byName);
 }
-function resolveUnset(unset = [], set = {}) {
-	if (!Array.isArray(unset)) throw new TypeError(`"unset" must be an array of attribute names`);
-	const names = new Set(unset);
-	for (const name of names) {
-		validateAttributeName(name);
-		if (Object.hasOwn(set, name)) throw new ConflictingMutationError(name);
-	}
-	return [...names];
+function assertSchema(schema) {
+	if (!isSchema(schema)) throw new SchemaDefinitionError("expected a schema built with defineSchema(...) — writes are typed by the schema they name");
+}
+function keysOf(values, operation) {
+	if (typeof values !== "object" || values === null) throw new TypeError(`The ${operation} values must be an object keyed by column name`);
+	return Object.keys(values);
+}
+function columnFor(schema, name, operation) {
+	const column = lookupColumn(schema, name);
+	if (column === void 0) throw new SchemaMismatchError(name, `the ${operation} names a column this schema does not have. Its columns are ` + describeColumns(schema));
+	return column;
+}
+/** One column's value, resolved, checked against the column's type, and encoded. */
+function encodeColumn(name, column, input) {
+	const value = toValue(input, name);
+	if (value.type !== column.type) throw new SchemaMismatchError(name, `a ${column.type} column, but the value is a ${value.type}. Write ${column.type}(...) around the value`);
+	return encodeAbiAttribute(name, value, column.isIndexed);
+}
+/** Throws if the `bytes` values among `attributes` add up to more than {@link MAX_ENTITY_BYTES}. */
+function assertBytesFit(attributes) {
+	let total = 0;
+	for (const { typeId, value } of attributes) if ((typeId & ~INDEXED_FLAG) === TYPE_IDS.bytes) total += (value.length - 2) / 2;
+	if (total > MAX_ENTITY_BYTES) throw new EntityTooLargeError(total, MAX_ENTITY_BYTES);
 }
 /**
 * The engine requires attributes **strictly ascending by their `bytes32` name**: that ordering is
@@ -807,13 +996,7 @@ function resolveUnset(unset = [], set = {}) {
 function byName(a, b) {
 	return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
 }
-/** Raw bytes as lowercase `0x` hex, without viem's hex-string ambiguity. */
-function toHexBytes(bytes) {
-	let out = "0x";
-	for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
-	return out;
-}
 
 //#endregion
-export { DECIMAL_UNIT as A, str as C, TYPE_IDS as D, u64 as E, TooManyAttributesError as F, UnknownAttributeTypeError as I, UntypedValueError as L, InvalidAttributeNameError as M, InvalidValueError as N, isArkivValue as O, MissingValueError as P, key as S, u256 as T, bytes32 as _, MAX_NAME_BYTES as a, decUnits as b, asTypeTag as c, I32_MIN as d, MAX_STRING_BYTES as f, bool as g, addr as h, encodeMutations as i, ConflictingMutationError as j, DECIMAL_SCALE as k, decodeRpcValue as l, U64_MAX as m, MAX_PAYLOAD_BYTES as n, isValidAttributeName as o, U256_MAX as p, encodeAttributes as r, validateAttributeName as s, MAX_ATTRIBUTES as t, I32_MAX as u, dec as v, toValue as w, i32 as x, decFromUnits as y };
-//# sourceMappingURL=attr-tmyREHtw.js.map
+export { key as A, DECIMAL_SCALE as B, bool as C, decFromUnits as D, dec as E, isColumn as F, InvalidValueError as G, ConflictingMutationError as H, INDEXED_FLAG as I, SchemaMismatchError as J, MissingValueError as K, TYPE_IDS as L, toValue as M, u256 as N, decUnits as O, u64 as P, isArkivValue as R, addr as S, bytes32 as T, EntityTooLargeError as U, DECIMAL_UNIT as V, InvalidAttributeNameError as W, UnknownAttributeTypeError as X, TooManyAttributesError as Y, UntypedValueError as Z, I32_MIN as _, SCHEMA_ATTRIBUTE as a, U256_MAX as b, isSchema as c, isValidAttributeName as d, validateAttributeName as f, I32_MAX as g, decodeTypeId as h, MAX_ATTRIBUTES as i, str as j, i32 as k, lookupColumn as l, decodeRpcValue as m, encodeCreate as n, defineSchema as o, asTypeTag as p, SchemaDefinitionError as q, encodePatch as r, describeColumns as s, MAX_ENTITY_BYTES as t, MAX_NAME_BYTES as u, MAX_BYTES_LENGTH as v, bytes as w, U64_MAX as x, MAX_STRING_BYTES as y, isIndexable as z };
+//# sourceMappingURL=schema-DY4sqehl.js.map