schemadef

const (
	FillStrategyULID    = "ulid"
	FillStrategyHandler = "handler"
)

FillStrategyULID and FillStrategyHandler are the only two values `forge:fill=` may take. See ColumnMarkerFill.

const (
	ColCreatedAt = "created_at"
	ColUpdatedAt = "updated_at"
	ColDeletedAt = "deleted_at"
)

managed column names recognized by convention.

const ColumnMarkerClosedSet = "forge:closed-set"

ColumnMarkerClosedSet declares that a CHECK constraint's value list mirrors a closed Go set: `COMMENT ON CONSTRAINT access_tokens_scopes ON access_tokens IS 'forge:closed-set accesstoken.AllScopes'`. Like ColumnMarkerRef it is a constraint comment — on the CHECK, not the column. `forge lint`'s closed-sets lane compares the list the migrations last defined with the named set and prints the migration that reconciles them (internal/closedset).

const ColumnMarkerFill = "forge:fill"

ColumnMarkerFill declares WHO fills a `forge:read-only` column that the generated Create/Update requests never carry a value for — the gap the unsatisfiable-column lint (internal/cli/lint/lint_unsatisfiable_columns.go) exists to close. Takes exactly one of two argument values, spelled `forge:fill=<strategy>`:

forge:fill=ulid     forge generates a ULID for this column at Create,
                    the same chokepoint (pkg/crud.Repo.Create) that
                    already ULID-generates an empty string PK. For a
                    non-PK column only — a share token, an invite code.
forge:fill=handler  pure acknowledgement: "I stamp this myself." Changes
                    no codegen behavior; its only mechanical effect is
                    suppressing the lint (and, where the CRUD shim is
                    scaffolded fresh, seeding an op.Entity FORGE_SCAFFOLD
                    reminder instead of a bare delegation).

`forge:fill=uuid` is deliberately NOT a strategy: forge pins postgres:17-alpine, where uuidv7() (time-ordered, postgres 18+) does not exist — only gen_random_uuid() (UUIDv4, random) is available. Forge's keyset pagination (pkg/crud's orderKeysetSafe) assumes pk-ascending insertion order; a random id would make every list page's order unpredictable. ULIDs are time-ordered and sort in creation order, which is why forge offers that strategy and not a UUID one.

const ColumnMarkerGoType = "forge:go-type"

ColumnMarkerGoType declares the Go type a column projects to on the generated entity struct, in place of the one forge derives from its SQL type: `forge:go-type=github.com/acme/app/gen/app/v1;appv1.ContentBlockType` for an enum kept as an integer, `forge:go-type=map[string]any` for a json document read as a map. The type must scan from and bind to the column (Bun's own rules: a named integer for an integer column, a map or struct for json). A qualified type names its import path, with `;<name>` when the package's name is not the path's last element — the go_package convention. Read with Column.GoTypeOverride.

const ColumnMarkerImmutable = "forge:immutable"

ColumnMarkerImmutable declares that a column must not be written by a full-replace UPDATE. It projects to Bun's `skipupdate` tag option.

const ColumnMarkerNoSoftDelete = "forge:no-soft-delete"

ColumnMarkerNoSoftDelete declares that a table's `deleted_at` column is an ordinary nullable timestamp, not forge's soft-delete tombstone: `COMMENT ON COLUMN worktrees.deleted_at IS 'forge:no-soft-delete'`.

By convention a time-typed deleted_at IS the soft-delete declaration — the generated Get, List and Update skip rows where it is set, and Delete stamps it instead of deleting. That is the right default and stays the default. But the same column name is also how a schema spells an ARCHIVE stamp, where an archived row must stay readable and writable and a delete must delete. Without a declaration the only way out was to route every query through the builder with WhereAllWithDeleted and ForceDelete, re-deriving by hand what the generated store should have said.

With the marker the column projects like any other nullable timestamp: no Bun ,soft_delete tag, no ListAll<E>, the column is writable by Update, every row is visible to Get and List, and Delete is a real DELETE. Only meaningful on deleted_at — on any other column it is rejected, because it would do nothing (see CheckMarkers).

const ColumnMarkerOwner = "forge:owner"

ColumnMarkerOwner declares that a column names WHO a row belongs to: the rows of this table are the property of distinct principals, and this is the column that says whose.

Forge ships no ownership of its own — no implicit scope, no ambient principal — and this marker does not change that. It injects no WHERE clause and changes no codegen, because only the application knows how a caller's claims map onto this column's values (a direct user id, a company id read from a membership table, an org resolved from a subdomain). Inventing that mapping is exactly the domain policy forge deliberately does not own. What the marker changes is what forge is willing to let SHIP.

It ARMS the `unscoped_auth` audit category. That category has always detected an authenticated RPC whose handler never resolves the caller, and has always reported it as advice, on the sound reasoning that a freshly-scaffolded project is entirely unscoped by construction: forge emits the delegations, the developer writes the scoping, and erroring would make forge's own output fail forge's own gate.

That reasoning conflated two different claims. "Unscoped" is a fact about handlers; "these rows belong to someone" is a fact about data, and forge could not previously observe the second one. A project that never says any row belongs to anyone has no boundary to breach. A project that declares this marker has stated the exact thing the fresh-scaffold argument assumed was unknowable — so from that point an authenticated RPC over this table that reads no caller is not a nudge, it is one principal reading (or writing) another's rows, and it fails the audit.

Measured, against a real downstream app: forge reported "63 of 74 authenticated RPCs never resolve the caller" and exited 0. Any authenticated user could read, update, delete and create rows belonging to every other one. The diagnosis was exactly right and nothing gated on it.

const ColumnMarkerReadable = "forge:readable"

ColumnMarkerReadable declares a column whose name looks like a credential but is not one, so the read-only role may read it: `COMMENT ON COLUMN usage_events.token_hash IS 'forge:readable — a content hash of the prompt, not of a credential'`. The reason is mandatory; it is the review record of an exception to the role's fail-closed default. Secret wins when both are declared.

const ColumnMarkerRef = "forge:ref"

ColumnMarkerRef declares which side of a two-paths-to-one-parent reference is authoritative (values: authoritative, derived-from=<col>, independent). Unlike ColumnMarkerImmutable it is declared on the FOREIGN KEY constraint, not the column — COMMENT ON CONSTRAINT, not COMMENT ON COLUMN — but it shares the same `forge:*` catalog-comment vocabulary, so it lives in this registry alongside it. Consumed by `forge db seed`'s diamond resolution; see pkg/seedplan/diamond.go for the full grammar and pkg/seedplan's `db/seeding` skill for the authoritative docs.

const ColumnMarkerSecret = "forge:secret"

ColumnMarkerSecret declares a column the database's read-only role (pkg/dbgrants) must never read: `COMMENT ON COLUMN git_credentials.access_token IS 'forge:secret'`. It is the SQL spelling of the proto `// forge:secret` field marker and the only one a column with no wire field can use — most credential tables have none. Either spelling withholds the column from the role; only the proto one also strips it from read responses.

const ColumnMarkerVersion = "forge:version"

ColumnMarkerVersion opts a column into optimistic concurrency control: pkg/crud's generic Repo requires Update/UpdateMasked's WHERE clause to still match the caller's last-read value and increments it atomically on a successful write. A write that loses the race — the value moved under a concurrent writer between that writer's read and this one's — fails with svcerr.ErrAborted (Connect code Aborted, "re-read and retry") instead of silently clobbering the other writer's change or reporting the row missing.

Unlike forge:immutable this column is NEVER caller-settable, not even via an explicit update_mask path: the repo owns the increment, and a client-supplied value would defeat the guarantee the marker exists to give. See forge/pkg/crud's meta.versionColumn for the write-path detail and internal/generator's bunTag for how the marker also becomes Bun's `,skipupdate` — defense in depth against a hand-rolled full-struct Bun query that bypasses the generic Repo entirely.

const TableMarkerAppendOnly = "forge:append-only"

TableMarkerAppendOnly declares that a table is an immutable ledger: rows may be inserted and read, never rewritten or erased. It is the STORAGE half of the `forge:append-only` proto marker, and it is what every post-birth pass reads.

It is declared in the migration rather than inferred from the proto for the same reason forge:immutable is: whether a row may be rewritten is a fact about STORAGE. The proto marker is a birth-time instruction that stops existing the moment the birth is over — it writes the trigger and omits the Update/Delete RPCs, and then nothing carries it forward. That is precisely how an append-only entity ended up with a generated store exposing UpdateX, UpdateXMasked and DeleteX: the only pass that had ever heard of the marker was the one that wrote the migration.

Declaring it on the table closes that, because the applied schema is the one truth every generate-time pass already reads. It is also honest about the general case: a table can be append-only because a hand-written migration made it so, with no proto marker anywhere.

const TableMarkerEntityName = "forge:entity-name"

TableMarkerEntityName declares the Go/wire name of the entity a table projects to: `COMMENT ON TABLE daemon_attachment IS 'forge:entity-name=DaemonAttachment'`. Without it the name is derived from the table (the singular, camel-cased), and a CRUD rpc's entity finds its table by that name, its plural or its singular. The declaration is for a table whose name derives to something else — an irregular plural, a prefix, a legacy spelling — so the entity, its store and any `Get<E>` rpc over it are named for what the table holds.

const TableMarkerNoEntity = "forge:no-entity"

TableMarkerNoEntity opts one table out of the generated data layer: no entity struct, no store, no delegates, no factory. Every other applied BASE TABLE is projected, whether or not a service declares CRUD rpcs for it — SQL is the schema truth, and the store follows the schema, not the wire. A table carrying it is plain schema reached through hand-written SQL (a migration bookkeeping table, a partition parent, a table another tool owns).

It is the per-table twin of the project-level `//forge:no-orm`, and it removes the table from the CRUD join too: a CRUD-named rpc over it is custom, as if the table did not exist.

const ViewMarkerEntity = "forge:entity"

ViewMarkerEntity opts a VIEW into the generated data layer as a READ-ONLY entity: `COMMENT ON VIEW chats_with_activity IS 'forge:entity'`. It gets the row struct plus List/Count, and Get<E>ByID by its key column — `id` when the view has one, or the one `forge:entity key=<column>` names. No write is generated: a view is a derived read. Views are opt-in because most are reporting conveniences nothing in Go reads.