RenewSessionIfStale implements sliding-window expiration. When a session is past its renewal threshold (less than half its renewal window remaining) i

ResolveTool finds an AgentTool by name or alias. Returns nil if not found.

RevokeAccessTokenFamily mirrors RevokeRefreshTokenFamily for access tokens. fosite calls these in pairs when revoking by request_id (the unified Revok

SetEmailSender attaches a transactional email sender. The apiKey is stored separately for deriving the unsubscribe HMAC secret. If the server is alre

SetOpLogGCConfig overrides the default sweep interval (1h) and minimum row age (24h). Pass 0 for either to keep the package default. Must be called be

SetSpawn injects the goroutine spawner used for deliveries. Passing the server's tracked-goroutine helper (Server.goAsync) makes Server.Stop() wait fo

SetUserPlanOverrides updates per-user limit overrides (JSON string).

StartOpLogGC kicks off the periodic prune-sweep loop. Idempotent — calling twice silently no-ops. Must be called AFTER SetCollabRoomManager; the loop

Subscribe registers a subscriber for itemID and returns a buffered channel of size subscriberBufSize.

TouchUserWrite updates last_write_at for a user, throttled to avoid write amplification. Only writes if the stored value is older than 5 minutes. Best

UnmarkStripeEventProcessed deletes a row from stripe_processed_events, allowing Stripe retries of the same event ID to be handled again (TASK-736). Us

UpdateItemWithPreCheck is UpdateItem with an optional pre-mutation hook that runs inside the same transaction (and, on Postgres, holds the same worksp

UpdateUser updates mutable user fields.

ValidatePartialFields validates ONLY the keys present in `patch` against the schema (TASK-2022, field-level PATCH / IDEA-1480). Unlike ValidateFields

ValidatePassword checks an email/password combination. Returns the user if valid, nil if the credentials are wrong (not an error).

ValidateToken hashes the provided plaintext token, looks it up in the database, checks expiry, and updates last_used_at. Returns nil if the token is i

VerifyClaimCode returns true if code matches the derived code for (userID, workspaceID) at the current OR previous time bucket — the sliding 5–10 minu

WorkspaceStorageUsage returns the total bytes consumed by non-deleted attachments in the workspace. Includes derived blobs (thumbnails) — those are re

WriteWorkspaceLink writes a .pad.toml in the given directory. serverURL is the base URL of the Pad server hosting this workspace. Pass the empty stri

apiRequest makes a JSON API request to the test server.

buildToolFromDef compiles a ToolDef into the mcp.Tool shape mcp-go expects. The schema is flat: `action` is required, every other parameter is optiona

conventionsCollection returns a Conventions collection scoped to the caller's domain. The trigger and scope select options are supplied by the caller

countIPChangeEvents returns the number of session_ip_changed rows in the audit log.

decryptUserTOTP decrypts the TOTP secret on a User struct in place.

displayWidth returns the visible column width of s: ANSI SGR escape sequences are stripped, then the remaining runes are counted. Every rune is approx

errStructured wraps a Go error into the standard MCP tool-error envelope (TASK-1077) with a stable identifier prefix (e.g. "pad_item.link"). Local hel

escapeTableCell escapes characters that would break a markdown table row: `|` becomes `\|`, and existing backslashes are doubled so the escape stays v

extractCommandBlock returns the substring of `md` covering one command's section, identified by its full path (e.g. "item create"). Used to scope asse

extractFieldValue pulls a named string field out of an item's fields JSON blob. Returns "" when the blob is empty, unparseable, or carries no string v

===================================================================== Helpers ===================================================================== fa

flexJSONToString accepts a raw JSON value and returns it as a canonical JSON-encoded string. Acceptable inbound shapes: - absent / empty / null → nil

isUUID is defined in handlers_items.go getWorkspaceDocument resolves workspace slug and document ID from URL params.

hasBootstrapToken reports whether a bootstrap token is currently configured. Lock-aware — safe to call without holding s.bootstrapMu. Used by handleSe

invalidate clears the cached entry for a workspace. Call after any mutation that changes used_bytes (uploads, deletes, transforms) so the next GET see

isAPITokenAuth returns true if the request was authenticated via an API token (not a session cookie or CLI session). Use this to gate sensitive operat

listTransitions returns all status_transitions rows for an item, oldest first.

markUploadInFlight increments the in-flight counter for a content hash. Returns a release func the caller MUST defer; the release decrements and remov

membersHandler returns an http.Handler that responds to any path with the standard `{members:[...], invitations:[]}` shape using the supplied rows.

Connected-apps store tests (PLAN-943 TASK-954). What's covered: - ListUserOAuthConnections deduplicates a chain across multiple access-token rows (r

normalizeStringEncodedJSONFields recursively walks a parsed JSON value, finds string-typed `fields` and `tags` properties, parses them as embedded JSO

packageHTTPResponse turns the recorded handler response into an MCP CallToolResult, mirroring ExecDispatcher's "JSON → structured + text fallback" beh

parseAttachmentFilename extracts the filename from a Content-Disposition header. Mirrors the CLI's helper of the same name (cmd/pad/main.go parseAttac

playbooksCollection returns a Playbooks collection scoped to the caller's domain. Like conventionsCollection, the trigger and scope select options are

publishItemEventWithName publishes a real-time event for item changes with actor name. `seq` is the item's workspace-scoped monotonic mutation cursor

recordInstallation stores a skill install in the global registry (~/.pad/installations.json).

registerPendingAck creates an entry in the room's pending-acks map keyed on requestID, expecting acks/brackets from `applier`. It seeds the bracket ba

renderItemTable is the testable core of PrintItemTable: it lays the item list out into maxWidth columns and writes to w. Columns are REF/TITLE · STATU

===================================================================== Translation helpers ============================================================

run executes fn on the injected spawner, or a plain goroutine if none is set.

runWorkspacePurgeSweep purges every workspace whose deleted_at is older than cutoff. Blobs are reclaimed BEFORE the DB rows are removed so a failed re

sanitizeFTSQuery wraps each token in double quotes so FTS5 treats special characters (like hyphens) as literals rather than operators. Only used for S

sanitizePGFTSQuery returns a copy of q with hyphens replaced by spaces. Used as the second leg of the OR-combined PG FTS query: postgres' english pars

seedCollabFixture creates the minimum fixture chain needed to test the collab WS endpoint: workspace + collection + item, all in the store, returning

seedUser creates a user that subsequent oauth tokens can use as their `subject`.

startMCPSessionTracker constructs the tracker + spawns the sweep goroutine. Called once at startup from SetMCPTransport (alongside startMCPAuditWriter

validateSessionCookie validates a session cookie and returns the user if valid, nil otherwise. A User-Agent change is logged but NOT rejected — this m

veErrorCode extracts the JSON error.code from a response, or "" if the body isn't an error envelope.

writeBootstrapToken drops a token file at <dataDir>/.bootstrap-token in the same shape EnsureBootstrapToken would produce — token + trailing newline,

AcquireParentChildrenLocks is the CANONICAL helper for taking `pad:parent-children:<id>` advisory locks. Every call site that needs to serialize again

Addr returns the host:port listen address.

AsPlanLimit returns the parsed plan-limit details when this APIError carries them, or nil otherwise. Returns nil for any error other than "plan_limit_

BaseURL returns the base URL for the API. If URL is set (via config, --url flag, or PAD_URL), it takes precedence. Otherwise, constructs from host and

CancelCustomer asks pad-cloud to cancel every active Stripe subscription for customerID and then delete the Stripe customer object. Used by handleDele

CapabilityLine returns the single-line capability bit a conforming CLI emits in response to `<cmd> help --capabilities` (or the `--cmdhelp-capabilitie

Clone overrides DefaultSession.Clone so the returned value is a *Session, not a *DefaultSession. Without this override, fosite's internal Clone() call

ConsumeEmailVerification atomically validates and marks a verification token as used, then sets users.email_verified_at to now. Returns the (now-verif

ConsumeTOTPStep atomically records a TOTP time-step as consumed, enforcing single-use semantics for login codes (BUG-2054). It succeeds only if step i

CreatePasswordReset generates a reset token for the given user. Returns the plaintext token (to embed in the reset URL). The token is stored as a SHA-

CreateWebhook registers a new webhook for a workspace.

Crop returns the rectangular sub-image bounded by `rect`. The rectangle is interpreted in the image's coordinate space (origin top-left) and intersect

Detect classifies a fetched document by inspecting its Content-Type header and the leading bytes of its body. It returns TypeOpenAPI when the document

FTSMatch returns the full-text search WHERE clause fragment. SQLite: "table MATCH ?" — consumes ONE arg. PostgreSQL: an OR-combined plainto_tsquery ma

GetAttachmentVariant returns the derived attachment row for parentID with the given variant key (e.g. "thumb-sm"), or (nil, nil) if no such row exists

GetAuthorizationCode hydrates the code's session. Returns ErrOAuthInvalidatedCode if the row exists but active=false (fosite triggers grant-family rev

GetChildItems returns all non-deleted child items linked to the given parent via item_links. Returns children from any collection.

--- Dashboard --- GetDashboard returns the workspace dashboard as raw JSON. The DashboardResponse type lives in the server package, so we use json.Raw

GetItemContentFlushedOpLogID returns the per-item flush watermark (TASK-1309). Returns (0, false) for items with NULL watermark or no row.

--- Child Item Progress --- GetItemProgress counts total and done child items linked to a parent via item_links. "Done" means the child item's done fi

GetOAuthProviders parses the JSON oauth_providers field into a string slice.

GetShareLink retrieves a share link by ID.

GuestVisibleResources returns the two-level visibility for a guest: - fullCollectionIDs: collections where the user has a direct collection grant (ful

ImportWorkspace imports a workspace from an exported data structure. It creates a new workspace with regenerated IDs, remapping all references. If new