@kavtuai/guildgate 0.1.0

package/dist/stores.d.ts

@@ -0,0 +1,73 @@
+import type { AuditEvent, BlockRecord, CacheEntry, IdempotencyBeginResult, IdempotencyRecord, MaintenanceState, OAuthCredentialRecord, OAuthStateRecord, OutboxRecord, RateLimitHitInput, RateLimitHitResult, SessionRecord } from "./types.js";
+export interface SessionStore {
+    get(idHash: string): Promise<SessionRecord | null>;
+    set(record: SessionRecord): Promise<void>;
+    delete(idHash: string): Promise<void>;
+    listByUser(userId: string): Promise<SessionRecord[]>;
+}
+export interface OAuthStateStore {
+    put(record: OAuthStateRecord): Promise<void>;
+    consume(stateHash: string, nowIso: string): Promise<OAuthStateRecord | null>;
+}
+export interface OAuthCredentialStore {
+    get(provider: string, userId: string): Promise<OAuthCredentialRecord | null>;
+    set(record: OAuthCredentialRecord): Promise<void>;
+    delete(provider: string, userId: string): Promise<void>;
+}
+export interface RateLimitStore {
+    hit(input: RateLimitHitInput): Promise<RateLimitHitResult>;
+    reset(key: string): Promise<void>;
+}
+export interface CacheStore {
+    get<T>(key: string): Promise<CacheEntry<T> | null>;
+    set<T>(key: string, entry: CacheEntry<T>): Promise<void>;
+    delete(key: string): Promise<void>;
+    deleteByTags(tags: string[]): Promise<number>;
+}
+export interface IdempotencyStore {
+    begin(record: IdempotencyRecord): Promise<IdempotencyBeginResult>;
+    complete(key: string, response: unknown, expiresAtMs: number): Promise<void>;
+    fail(key: string): Promise<void>;
+    get(key: string): Promise<IdempotencyRecord | null>;
+}
+export interface LockStore {
+    acquire(key: string, token: string, ttlMs: number, waitMs: number): Promise<boolean>;
+    release(key: string, token: string): Promise<void>;
+}
+export interface AuditStore {
+    write(event: AuditEvent): Promise<void>;
+    list?(filter?: {
+        userId?: string;
+        action?: string;
+        limit?: number;
+    }): Promise<AuditEvent[]>;
+}
+export interface OutboxStore {
+    enqueue(record: OutboxRecord): Promise<void>;
+    next(limit: number): Promise<OutboxRecord[]>;
+    markPublished(id: string, publishedAt: string): Promise<void>;
+    markFailed(id: string, error: string): Promise<void>;
+}
+export interface PolicyStore {
+    getMaintenance(): Promise<MaintenanceState>;
+    setMaintenance(state: MaintenanceState): Promise<void>;
+    getBlock(subjectType: BlockRecord["subjectType"], subjectId: string, nowIso: string): Promise<BlockRecord | null>;
+    putBlock(record: BlockRecord): Promise<void>;
+    removeBlock(subjectType: BlockRecord["subjectType"], subjectId: string): Promise<void>;
+    getPolicyVersion(): Promise<number>;
+    bumpPolicyVersion(): Promise<number>;
+}
+export interface GuildGateStores {
+    sessions: SessionStore;
+    oauthStates: OAuthStateStore;
+    credentials: OAuthCredentialStore;
+    rateLimits: RateLimitStore;
+    cache: CacheStore;
+    idempotency: IdempotencyStore;
+    locks: LockStore;
+    audit: AuditStore;
+    outbox: OutboxStore;
+    policies: PolicyStore;
+}
+export declare function composeStores(base: GuildGateStores, overrides: Partial<GuildGateStores>): GuildGateStores;
+//# sourceMappingURL=stores.d.ts.map

package/dist/stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../src/stores.ts"],"names":[],"mappings":"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"}

package/dist/stores.js

@@ -0,0 +1,4 @@
+export function composeStores(base, overrides) {
+    return { ...base, ...overrides };
+}
+//# sourceMappingURL=stores.js.map

package/dist/stores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.js","sourceRoot":"","sources":["../src/stores.ts"],"names":[],"mappings":"AA4FA,MAAM,UAAU,aAAa,CAAC,IAAqB,EAAE,SAAmC;IACtF,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,SAAS,EAAE,CAAC;AACnC,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,32 @@
+import { type GuildGateConfig } from "./kernel.js";
+import type { SupportedLocale } from "./types.js";
+export declare function createGuildGateTestHarness(overrides?: Partial<GuildGateConfig>): {
+    kernel: import("./kernel.js").GuildGateKernel;
+    stores: import("./stores.js").GuildGateStores;
+    login(userId?: string, locale?: SupportedLocale): Promise<{
+        session: import("./types.js").SessionRecord;
+        sessionToken: string;
+        csrfToken: string;
+        setCookie: string;
+    }>;
+    request(input: {
+        method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        body?: unknown;
+        sessionToken?: string;
+        csrfToken?: string;
+        idempotencyKey?: string;
+        locale?: SupportedLocale;
+    }): {
+        readonly method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+        readonly path: "/test";
+        readonly input: unknown;
+        readonly origin: "http://localhost:3000";
+        readonly ip: "127.0.0.1";
+        readonly userAgent: "guildgate-test";
+        readonly sessionToken: string | undefined;
+        readonly csrfToken: string | undefined;
+        readonly idempotencyKey: string | undefined;
+        readonly locale: SupportedLocale;
+    };
+};
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,wBAAgB,0BAA0B,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC;;;oCAuCpC,eAAe;;;;;;mBAGvC;QACb,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;QACrD,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,eAAe,CAAC;KAC1B;;;;;;;;;;;;EAeJ"}

package/dist/testing.js

@@ -0,0 +1,60 @@
+import { createMemoryStoreBundle } from "./memory-store.js";
+import { createGuildGate } from "./kernel.js";
+export function createGuildGateTestHarness(overrides) {
+    const stores = createMemoryStoreBundle();
+    const defaultSecurity = {
+        allowedOrigins: ["http://localhost:3000"],
+        csrfSecret: "test-csrf-secret-that-is-long-enough-123456",
+        auditIpSalt: "test-audit-salt-123456",
+        session: {
+            ttlMs: 60 * 60_000,
+            idleTimeoutMs: 30 * 60_000,
+            rotateAfterMs: 15 * 60_000,
+            maximumSessionsPerUser: 5,
+        },
+    };
+    const config = {
+        app: {
+            name: overrides?.app?.name ?? "GuildGate Test",
+            environment: overrides?.app?.environment ?? "test",
+            baseUrl: overrides?.app?.baseUrl ?? "http://localhost:3000",
+        },
+        owners: overrides?.owners ?? ["owner-1"],
+        locale: overrides?.locale ?? { default: "en" },
+        security: {
+            ...defaultSecurity,
+            ...overrides?.security,
+            session: {
+                ...defaultSecurity.session,
+                ...overrides?.security?.session,
+            },
+        },
+        stores: overrides?.stores ?? stores,
+        realtime: overrides?.realtime,
+        audit: overrides?.audit,
+        clock: overrides?.clock,
+    };
+    const kernel = createGuildGate(config);
+    return {
+        kernel,
+        stores: config.stores,
+        async login(userId = "user-1", locale = "en") {
+            return kernel.createSession({ userId, locale });
+        },
+        request(input) {
+            return {
+                method: input.method ?? "POST",
+                path: "/test",
+                input: input.body,
+                origin: "http://localhost:3000",
+                ip: "127.0.0.1",
+                userAgent: "guildgate-test",
+                sessionToken: input.sessionToken,
+                csrfToken: input.csrfToken,
+                idempotencyKey: input.idempotencyKey,
+                locale: input.locale ?? "en",
+            };
+        },
+    };
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAwB,MAAM,aAAa,CAAC;AAGpE,MAAM,UAAU,0BAA0B,CAAC,SAAoC;IAC7E,MAAM,MAAM,GAAG,uBAAuB,EAAE,CAAC;IACzC,MAAM,eAAe,GAAgC;QACnD,cAAc,EAAE,CAAC,uBAAuB,CAAC;QACzC,UAAU,EAAE,6CAA6C;QACzD,WAAW,EAAE,wBAAwB;QACrC,OAAO,EAAE;YACP,KAAK,EAAE,EAAE,GAAG,MAAM;YAClB,aAAa,EAAE,EAAE,GAAG,MAAM;YAC1B,aAAa,EAAE,EAAE,GAAG,MAAM;YAC1B,sBAAsB,EAAE,CAAC;SAC1B;KACF,CAAC;IACF,MAAM,MAAM,GAAoB;QAC9B,GAAG,EAAE;YACH,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,IAAI,gBAAgB;YAC9C,WAAW,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,IAAI,MAAM;YAClD,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,IAAI,uBAAuB;SAC5D;QACD,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC,SAAS,CAAC;QACxC,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE;QAC9C,QAAQ,EAAE;YACR,GAAG,eAAe;YAClB,GAAG,SAAS,EAAE,QAAQ;YACtB,OAAO,EAAE;gBACP,GAAG,eAAe,CAAC,OAAO;gBAC1B,GAAG,SAAS,EAAE,QAAQ,EAAE,OAAO;aAChC;SACF;QACD,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,MAAM;QACnC,QAAQ,EAAE,SAAS,EAAE,QAAQ;QAC7B,KAAK,EAAE,SAAS,EAAE,KAAK;QACvB,KAAK,EAAE,SAAS,EAAE,KAAK;KACxB,CAAC;IACF,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,OAAO;QACL,MAAM;QACN,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,QAAQ,EAAE,SAA0B,IAAI;YAC3D,OAAO,MAAM,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAClD,CAAC;QACD,OAAO,CAAC,KAOP;YACC,OAAO;gBACL,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,MAAM;gBAC9B,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,MAAM,EAAE,uBAAuB;gBAC/B,EAAE,EAAE,WAAW;gBACf,SAAS,EAAE,gBAAgB;gBAC3B,YAAY,EAAE,KAAK,CAAC,YAAY;gBAChC,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,cAAc,EAAE,KAAK,CAAC,cAAc;gBACpC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;aACpB,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,183 @@
+export type EnvironmentName = "development" | "test" | "production";
+export type SupportedLocale = "en" | "tr";
+export type HttpMethod = "GET" | "HEAD" | "OPTIONS" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface Clock {
+    now(): Date;
+}
+export declare const systemClock: Clock;
+export interface SessionRecord {
+    idHash: string;
+    userId: string;
+    locale: SupportedLocale;
+    createdAt: string;
+    lastSeenAt: string;
+    expiresAt: string;
+    idleExpiresAt: string;
+    rotateAfter: string;
+    revokedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface OAuthStateRecord {
+    stateHash: string;
+    returnTo: string;
+    locale: SupportedLocale;
+    createdAt: string;
+    expiresAt: string;
+    metadata?: Record<string, unknown>;
+}
+export interface OAuthCredentialRecord {
+    provider: "discord" | string;
+    userId: string;
+    accessTokenCiphertext: string;
+    refreshTokenCiphertext: string;
+    scope: string;
+    tokenType: string;
+    expiresAt: string;
+    updatedAt: string;
+}
+export interface AuditActor {
+    type: "user" | "owner" | "system" | "anonymous";
+    userId?: string;
+    sessionIdHash?: string;
+}
+export interface ResourceRef {
+    type: string;
+    id: string;
+}
+export interface AuditEvent {
+    id: string;
+    requestId: string;
+    action: string;
+    actor: AuditActor;
+    resource?: ResourceRef;
+    result: "success" | "denied" | "failed";
+    reasonCode?: string;
+    policyVersion: number;
+    changes?: unknown;
+    metadata: {
+        ipHash?: string;
+        userAgent?: string;
+        durationMs: number;
+    };
+    createdAt: string;
+}
+export interface RealtimeEvent<T = unknown> {
+    version: 1;
+    id: string;
+    sequence?: number;
+    event: string;
+    channel: string;
+    timestamp: string;
+    data: T;
+}
+export interface OutboxRecord {
+    id: string;
+    event: RealtimeEvent;
+    createdAt: string;
+    publishedAt?: string;
+    attempts: number;
+    lastError?: string;
+}
+export interface BlockRecord {
+    subjectType: "user" | "guild" | "ip";
+    subjectId: string;
+    reason: string;
+    createdAt: string;
+    expiresAt?: string;
+}
+export interface MaintenanceState {
+    enabled: boolean;
+    reason?: string;
+    allowOwners: boolean;
+    updatedAt: string;
+}
+export interface RateLimitHitInput {
+    key: string;
+    limit: number;
+    windowMs: number;
+    nowMs: number;
+    cost?: number;
+}
+export interface RateLimitHitResult {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    resetAtMs: number;
+    retryAfterMs: number;
+}
+export interface CacheEntry<T = unknown> {
+    value: T;
+    expiresAtMs: number;
+    staleUntilMs?: number;
+    tags: string[];
+}
+export type IdempotencyState = "inflight" | "completed";
+export interface IdempotencyRecord {
+    key: string;
+    requestHash: string;
+    state: IdempotencyState;
+    response?: unknown;
+    createdAtMs: number;
+    expiresAtMs: number;
+}
+export type IdempotencyBeginResult = {
+    status: "started";
+} | {
+    status: "inflight";
+} | {
+    status: "conflict";
+} | {
+    status: "completed";
+    response: unknown;
+};
+export interface RequestEnvelope {
+    method: HttpMethod;
+    path: string;
+    input: unknown;
+    headers?: Record<string, string | string[] | undefined>;
+    cookies?: Record<string, string | undefined>;
+    ip?: string;
+    origin?: string;
+    userAgent?: string;
+    requestId?: string;
+    locale?: SupportedLocale | string;
+    sessionToken?: string;
+    csrfToken?: string;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export interface SessionResolution {
+    session: SessionRecord | null;
+    replacementToken?: string;
+    replacementCsrfToken?: string;
+    clearCookie?: boolean;
+}
+export interface PostCommitIssue {
+    stage: "cache" | "realtime" | "audit";
+    code: string;
+}
+export interface ActionExecutionMeta {
+    requestId: string;
+    locale: SupportedLocale;
+    rateLimit?: RateLimitHitResult;
+    replacementSessionToken?: string;
+    replacementCsrfToken?: string;
+    clearSessionCookie?: boolean;
+    postCommitIssues?: PostCommitIssue[];
+}
+export type ActionExecutionResult<T> = {
+    ok: true;
+    data: T;
+    meta: ActionExecutionMeta;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        status: number;
+        retryable: boolean;
+        details?: Record<string, unknown>;
+    };
+    meta: ActionExecutionMeta;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,4 @@
+export const systemClock = {
+    now: () => new Date(),
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,WAAW,GAAU;IAChC,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;CACtB,CAAC"}

package/docs/WRITING_STYLE.md

@@ -0,0 +1,118 @@
+# Writing rules
+
+This file defines the editorial rules for GuildGate documentation, errors, examples, release notes, and repository pages.
+
+The checklist is based on the Wikipedia essay **Signs of AI writing**, reviewed on 25 July 2026. The essay states that these signs are clues, not proof that a text was produced by a model. GuildGate uses the list as an editing checklist, not as an authorship detector.
+
+Source: https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing
+
+## Content patterns to remove
+
+1. **Unearned importance.** Do not claim that a small function marks a major shift, leaves a lasting legacy, changes an industry, or reflects a wider movement without evidence.
+2. **Notability padding.** Do not add vague claims about press attention, experts, communities, or independent coverage. Name the source and state what it supports.
+3. **Shallow interpretation.** Do not attach generic meaning to a fact. Explain the actual effect on a request, database record, session, or operator.
+4. **Promotional wording.** Remove sales copy from technical sections. State behavior, limits, and trade-offs.
+5. **Vague attribution.** Avoid phrases such as “many developers say,” “it is widely known,” or “experts agree.” Provide a named source or omit the claim.
+6. **Generic challenge sections.** Do not add a “Challenges and future prospects” section unless it contains project-specific open work, owners, and acceptance criteria.
+7. **Topic-name repetition.** Do not treat a broad subject as a proper name and repeat it in every paragraph.
+8. **Unsupported trends.** Avoid claims about growing demand, rapid adoption, changing expectations, or industry direction unless current evidence is cited.
+
+## Word and sentence patterns to watch
+
+These words are not forbidden in isolation. They require a reason. Replace them when they hide a specific verb or fact:
+
+- additionally
+- align with
+- boasts
+- bolstered
+- crucial
+- delve
+- emphasizing
+- enduring
+- enhance
+- fostering
+- garner
+- highlight
+- interplay
+- intricate
+- key
+- landscape
+- meticulous
+- pivotal
+- robust
+- showcase
+- tapestry
+- testament
+- underscore
+- valuable
+- vibrant
+
+Other sentence habits to remove:
+
+- Avoiding plain forms of “is,” “has,” or “does” and replacing them with inflated verbs.
+- “Not only X, but also Y,” “not X but Y,” or “X rather than Y” used as decoration.
+- Three adjectives, three benefits, or three clauses added to make a sentence sound complete.
+- Repeating the same noun through strained synonyms only to avoid repetition.
+- Opening paragraphs with stock transitions such as “In today’s fast-paced world.”
+- Closing sections with a restatement that adds no new instruction.
+
+## Formatting patterns to remove
+
+- Title Case On Every Heading.
+- Bold text used for ordinary words or nearly every bullet.
+- A vertical list where each item starts with an inline bold heading but the items contain no useful detail.
+- Repeated em dashes where commas, periods, or parentheses are clearer.
+- Decorative emoji in technical pages, errors, changelogs, or security documents.
+- Tables used only to make sparse content look substantial.
+- Curly quotation marks copied into code, configuration, or shell commands.
+- Skipped heading levels.
+- Horizontal rules placed before every heading.
+- Markdown syntax pasted into a surface that does not render Markdown.
+
+## User-directed boilerplate to remove
+
+Do not publish assistant-like conversation fragments:
+
+- Offers to continue, expand, rewrite, or help with another task.
+- Statements about a knowledge cutoff.
+- Speculation about what the reader “might want.”
+- “Here is a polished version,” “certainly,” “hope this helps,” or similar framing.
+- Empty placeholders such as `[insert name]`, `[add source]`, or `TODO` in a release artifact.
+- Template instructions left in final text.
+- Refusals, prompt references, or descriptions of how the text was generated.
+
+## Markup and citation artifacts to reject
+
+Repository checks must reject or flag these before release:
+
+- Broken Markdown fences, links, reference labels, or HTML fragments.
+- Wiki markup in Markdown files.
+- Internal model citation strings such as `contentReference`, `oaicite`, `turn0search`, `attributableIndex`, or `+1` citation markers.
+- Provider artifacts such as Gemini citation spans, Grok cards, DeepSeek daggers, Perplexity upload references, or `:::writing` blocks.
+- Nonexistent templates, categories, files, imports, commands, environment variables, or package exports.
+- Tracking query strings such as `utm_source` in source links.
+- DOI, ISBN, package, or documentation links that do not resolve or do not support the nearby statement.
+- Citations declared but never used.
+
+## Repository-specific rules
+
+1. Use one language per file. `README.md` is English; `README.tr.md` is Turkish.
+2. Name the actor. Use “the kernel,” “the store,” “the application,” “Discord,” or “the operator” instead of “the system” when possible.
+3. Name the failure. Use `CSRF_INVALID`, `RATE_LIMITED`, or the concrete condition instead of “something went wrong.”
+4. Separate guarantees from recommendations. “Rejects HTTP origins in production” is a guarantee. “Use Redis for multiple instances” is a recommendation.
+5. State ownership. Database transactions, schema migrations, proxy trust, secret storage, and backup policy belong to the application unless a GuildGate component explicitly implements them.
+6. Avoid absolute security claims. Do not write “unhackable,” “zero risk,” “fully secure,” or “bug-free.”
+7. Examples must compile or be clearly marked as pseudocode.
+8. Every environment variable used in an example must appear in `.env.example` or be explained next to the example.
+9. Every public export used in documentation must exist in `package.json` and the built declaration files.
+10. Keep paragraphs short enough to scan, but do not split one sentence into a decorative list.
+
+## Release review
+
+Before a release:
+
+- Search the repository for the word list above and review each match.
+- Search for provider citation artifacts and placeholder brackets.
+- Run links, code samples, tests, type checks, package dry-run, and the doctor command.
+- Read each changed page once without editing. Mark sentences that claim importance without explaining behavior.
+- Ask a reviewer to check correctness, not whether the prose “sounds human.”

package/docs/architecture.md

@@ -0,0 +1,83 @@
+# Architecture
+
+GuildGate separates policy, transport, Discord access, and storage. The core package does not import Fastify, Express, Redis, PostgreSQL, MongoDB, or a WebSocket server.
+
+## Components
+
+1. **Kernel** checks sessions, origins, CSRF tokens, blocks, maintenance state, limits, authorization, idempotency, locks, deadlines, audit records, cache tags, and realtime delivery.
+2. **Session manager** stores only a SHA-256 hash of the opaque session token. Expiry, idle expiry, rotation, caps, and revocation are enforced at resolution time.
+3. **Discord OAuth client** creates one-time state records, binds state to a browser nonce, exchanges codes, encrypts credentials, refreshes access tokens, and revokes credentials.
+4. **Discord authorizer** compares the user’s OAuth guild permissions with the bot’s current guild roles and permissions.
+5. **Store interfaces** allow each application to select storage. Durable and short-lived records can use different services.
+6. **Framework adapters** translate request and response objects without placing framework types in the core package.
+7. **Realtime hub** authenticates connections, authorizes each subscription, limits messages, handles slow clients, and closes sessions on revocation.
+8. **Outbox dispatcher** publishes committed events from a durable outbox implementation.
+
+The component diagram is in [`uml/components.mmd`](./uml/components.mmd).
+
+## Action order
+
+The default order for an unsafe authenticated request is:
+
+1. Resolve and, when due, rotate the session.
+2. Check the exact request origin.
+3. Validate the CSRF token against the session hash.
+4. Parse input.
+5. Resolve the protected resource.
+6. Apply maintenance and block policies.
+7. Apply the action rate limit.
+8. Run application or Discord authorization.
+9. Reserve the idempotency key.
+10. Acquire the resource lock.
+11. Run the operation under one deadline.
+12. Complete the idempotency record before non-transactional follow-up work.
+13. Invalidate cache tags.
+14. Enqueue or publish realtime events.
+15. Write the audit event.
+16. Release the lock.
+
+See [`uml/action-sequence.mmd`](./uml/action-sequence.mmd).
+
+## Transaction boundary
+
+GuildGate cannot create a transaction for an unknown database driver. The action’s `execute()` function owns the database transaction.
+
+For a setting write, the application should place these changes in one transaction where possible:
+
+- Read or compare the current revision.
+- Write the new setting record.
+- Write the application’s domain audit record if it must be atomic with the setting.
+- Write a durable outbox row.
+
+GuildGate’s general audit store runs after `execute()`. Use `audit.failClosedActions` only when refusing the response after an audit failure is useful. It cannot undo a transaction that has already committed. A high-risk operation that requires atomic audit must write its domain audit inside `execute()`.
+
+## Consistency choices
+
+- **Session and OAuth state:** consistent, single-use, fail closed.
+- **Idempotency and distributed locks:** atomic store operations are required for multiple instances.
+- **Guild display data:** short cache duration is acceptable.
+- **Permission-sensitive writes:** use live Discord checks or a bot gateway cache that is invalidated by member and role events.
+- **Audit and outbox:** durable storage is recommended.
+- **Realtime delivery:** an event may be delivered after commit. Use an outbox when delivery must survive process restarts.
+
+## Failure policy
+
+The kernel fails closed when it cannot establish authentication, CSRF validity, origin validity, a block policy, a required rate limit, authorization, idempotency ownership, or a resource lock.
+
+The application chooses what to do when cache, audit, or realtime delivery fails. Current action behavior is:
+
+- Cache invalidation, realtime publication, and outbox enqueue failures are returned as `meta.postCommitIssues`; the committed operation is not repeated.
+- General audit failure is also reported as a post-commit issue. It fails the response only when the action name is in `audit.failClosedActions`.
+- An audit fail-closed action must use idempotency so a client retry cannot repeat an operation that may already be committed.
+
+A production adapter can add retries, queues, or driver-specific handling around these interfaces.
+
+## Trust boundaries
+
+- The browser is untrusted.
+- Route parameters, body fields, headers, locale values, and channel names are untrusted.
+- OAuth access does not grant bot permissions.
+- A cached guild list is not permanent authorization.
+- A reverse proxy header is trusted only when the application has configured the proxy chain.
+- Store implementations are trusted code and must preserve atomic semantics stated by their interfaces.
+- Realtime transport libraries are responsible for TLS termination and frame parsing. The GuildGate hub starts after the transport accepts a connection.