# Cookies

Register a cookie, then read and write through `Cookies`. `Cookies.set` and `Cookies.setAuthId` return an admission boolean — not a durability acknowledgement.

```ts
import { Cookies, Clients, command, HookResult } from '@s2script/sdk';

const boots = Cookies.register('demo_boots', { default: '0' });

export function OnPluginStart(): void {
	command('sm_toggle_boots', (cmd) => {
		const client = Clients.fromSlot(cmd.callerSlot);
		if (!client || client.steamId === '0') return HookResult.Handled;

		const next = Cookies.get(client, boots) === '1' ? '0' : '1';
		if (!Cookies.set(client, boots, next)) {
			cmd.reply('preference rejected; retry when persistence capacity recovers');
			return HookResult.Handled;
		}
		cmd.reply(`boots=${Cookies.get(client, boots)} (DB commit is asynchronous)`);
		return HookResult.Handled;
	});
}
```

`false` means admission was rejected: the identity is invalid, stale, or a bot (`"0"`), or the bounded host persistence outbox cannot reserve capacity. Rejection leaves the cache unchanged. Check `false` and report, shed, or retry. Structural mocks must return `boolean`, not `void`.

`true` means the host accepted the write into the outbox before mutating the cache. The host keeps ownership until the database acknowledges it, including across [clientprefs](https://s2script.com/plugins/clientprefs) reload and same-process core reinit. Process exit or library destruction can still lose unacknowledged writes.

`Cookies.setAuthId(steamId, cookie, value)` uses the same contract for an online or offline SteamID64 (`SetAuthIdCookie` parity). `false` leaves both cache and outbox unchanged (including empty / `"0"` identity).

Read stored values after `OnClientCookiesCached` or `Cookies.areCached(client)`.

## Persistence

clientprefs is the sole cookie-table writer. Plugins must not issue unconditional cookie upserts (`INSERT OR REPLACE`). Versioned SQLite rows use `writer_epoch` plus an int64 `revision`; a conditional UPSERT rejects older late writes.

First adoption of the versioned cookie schema needs matched core and clientprefs artifacts installed with the server stopped, then a fresh process. Do not hot-load a newer clientprefs over an older generation with unversioned cookie writes still in flight.

See the [cookies module](https://s2script.com/docs/api/modules/cookies).