@nsshunt/stsdatamanagement 1.18.196 → 1.18.199

package/db-scripts/builddb-stsrest01.sql

@@ -0,0 +1,2176 @@
+-- =============================================================================
+-- stsrest01 - Generic Resource / Entity Database Model
+-- =============================================================================
+--
+-- PURPOSE
+-- -------
+-- This schema implements a deliberately generic, versioned resource/entity
+-- model.
+--
+-- A RESOURCE is a logical/conceptual container identified by resname.
+-- A RESOURCE version is represented by a new stsresource row and therefore a
+-- new stsresource.oid.
+--
+-- An ENTITY belongs to the RESOURCE CONCEPT, not permanently to one historical
+-- resource row. For that reason, whenever the current resource version changes,
+-- all entity history is moved to the new current resource OID.
+--
+-- This is intentional and is important to the design:
+--
+--     resource v1 (oid 10)
+--         entity history -> resourceoid 10
+--
+--     resource updated to v2 (oid 11)
+--         entity history -> resourceoid 11
+--
+--     resource deleted as v3 (oid 12)
+--         entity history -> resourceoid 12
+--
+--     resource recreated / reinstated as v4 (oid 13)
+--         entity history -> resourceoid 13
+--
+-- A delete therefore does NOT terminate the logical resource concept.
+-- Recreating a deleted resource continues the resource version sequence and
+-- restores the same concept, including its entity history.
+--
+-- dbaction values
+-- ---------------
+--     1 = create / recreate
+--     2 = update
+--     3 = logical delete
+--
+-- VERSIONING RULES
+-- ----------------
+-- * Historical rows have validto IS NOT NULL.
+-- * Exactly one row per resource concept may have validto IS NULL.
+-- * A deleted resource is still the current resource version; it has
+--   validto IS NULL and dbaction = 3.
+-- * Exactly one row per entity concept may have validto IS NULL.
+-- * A deleted entity is likewise represented by a current tombstone row with
+--   dbaction = 3.
+-- * Recreating a deleted resource/entity closes the tombstone and creates the
+--   next version. Version numbers never reset to 1.
+--
+-- CONCURRENCY RULES
+-- -----------------
+-- Mutating functions lock the current resource/entity rows with FOR UPDATE
+-- before changing versions. Partial unique indexes provide a final database
+-- invariant for concurrent creates where there is no existing row to lock.
+--
+-- JSON
+-- ----
+-- resdesc and entvalue retain the supplied JSON text.
+-- resdesc_jsonb and entvalue_jsonb retain the parsed JSON representation for
+-- indexing/searching without making the model resource-type-specific.
+--
+-- =============================================================================
+
+
+-- =============================================================================
+-- Sequences
+-- =============================================================================
+
+-- Generates immutable surrogate OIDs for stsresource rows.
+--
+-- An OID identifies one database row/version; it is NOT the permanent logical
+-- identity of a resource. resname is the logical resource concept identifier.
+CREATE SEQUENCE public.stsresource_oid_seq
+    AS bigint
+    INCREMENT 1
+    START 1
+    MINVALUE 1
+    CACHE 1;
+
+ALTER SEQUENCE public.stsresource_oid_seq
+    OWNER TO postgres;
+
+
+-- Generates immutable surrogate OIDs for stsentity rows.
+--
+-- An entity OID identifies one entity version row.
+CREATE SEQUENCE public.stsentity_oid_seq
+    AS bigint
+    INCREMENT 1
+    START 1
+    MINVALUE 1
+    CACHE 1;
+
+ALTER SEQUENCE public.stsentity_oid_seq
+    OWNER TO postgres;
+
+
+-- =============================================================================
+-- stsresource
+-- =============================================================================
+
+-- Stores the complete version history for every generic resource concept.
+--
+-- resname
+--     Logical identifier of the resource concept.
+--
+-- resdesc
+--     Original JSON text supplied by the caller.
+--
+-- resdesc_jsonb
+--     Parsed JSON representation of resdesc. This permits generic JSONB
+--     searching/indexing while preserving the original text.
+--
+-- vnum
+--     Monotonically increasing version number within a resname.
+--
+-- validfrom / validto
+--     Temporal validity interval for this version. The current version has
+--     validto IS NULL.
+--
+-- dbaction
+--     1=create/recreate, 2=update, 3=logical delete.
+--
+-- dbactionuser
+--     Application/user identity responsible for the database change.
+CREATE TABLE public.stsresource
+(
+    oid             bigint NOT NULL
+                    DEFAULT nextval('public.stsresource_oid_seq'::regclass),
+
+    resname         character varying(128)
+                    COLLATE pg_catalog."default"
+                    NOT NULL,
+
+    resdesc         character varying(32768)
+                    COLLATE pg_catalog."default",
+
+    resdesc_jsonb   jsonb,
+
+    vnum            bigint NOT NULL,
+
+    validfrom       timestamp with time zone NOT NULL,
+    validto         timestamp with time zone,
+
+    dbaction        smallint NOT NULL,
+
+    dbactionuser    character varying(64)
+                    COLLATE pg_catalog."default"
+                    NOT NULL,
+
+    CONSTRAINT stsresource_pkey
+        PRIMARY KEY (oid),
+
+    CONSTRAINT stsresource_dbaction_check
+        CHECK (dbaction IN (1, 2, 3))
+)
+TABLESPACE pg_default;
+
+ALTER TABLE public.stsresource
+    OWNER TO postgres;
+
+-- Make the sequence lifecycle follow its dedicated table column.
+ALTER SEQUENCE public.stsresource_oid_seq
+    OWNED BY public.stsresource.oid;
+
+
+-- -----------------------------------------------------------------------------
+-- stsresource indexes
+-- -----------------------------------------------------------------------------
+
+-- A resource concept may have only one row for each version number.
+CREATE UNIQUE INDEX stsresource_resname_vnum
+    ON public.stsresource USING btree
+    (
+        resname COLLATE pg_catalog."default" ASC NULLS LAST,
+        vnum ASC NULLS LAST
+    )
+    TABLESPACE pg_default;
+
+
+-- Database invariant: exactly zero or one CURRENT row may exist for resname.
+--
+-- IMPORTANT:
+-- Do NOT filter dbaction = 3 here.
+--
+-- A logically deleted resource is still the current resource version until it
+-- is recreated. This index prevents a deleted tombstone and an active row from
+-- both being current at the same time.
+CREATE UNIQUE INDEX idx_stsresource_resname_one_current
+    ON public.stsresource (resname)
+    WHERE validto IS NULL;
+
+
+-- Supports general resource history/current-version lookup.
+--
+-- This index intentionally includes deleted current records.
+CREATE INDEX stsresource_resname_validto
+    ON public.stsresource USING btree
+    (
+        resname COLLATE pg_catalog."default" ASC NULLS LAST,
+        validto DESC NULLS LAST
+    )
+    TABLESPACE pg_default;
+
+
+-- Supports normal application reads and keyset/cursor pagination over active
+-- resources only.
+--
+-- oid is included after resname to provide a deterministic ordered key.
+CREATE INDEX idx_stsresource_resname_current
+    ON public.stsresource (resname, oid)
+    WHERE validto IS NULL
+      AND dbaction != 3;
+
+
+-- =============================================================================
+-- stsentity
+-- =============================================================================
+
+-- Stores the complete version history for entities belonging to a resource
+-- concept.
+--
+-- resourceoid
+--     Points to the CURRENT stsresource row for the resource concept.
+--
+--     This value intentionally changes whenever the resource gets a new
+--     version. All entity history is migrated to the new resource OID by the
+--     resource update/delete/recreate functions.
+--
+-- entname
+--     Logical identifier of the entity within its resource concept.
+--
+-- entvalue
+--     Original JSON text supplied by the caller.
+--
+-- entvalue_jsonb
+--     Parsed JSON representation of entvalue.
+--
+-- vnum
+--     Monotonically increasing entity version number.
+--
+-- validfrom / validto
+--     Temporal validity interval for this entity version. The current version
+--     has validto IS NULL.
+--
+-- dbaction
+--     1=create/recreate, 2=update, 3=logical delete.
+CREATE TABLE public.stsentity
+(
+    oid             bigint NOT NULL
+                    DEFAULT nextval('public.stsentity_oid_seq'::regclass),
+
+    resourceoid     bigint NOT NULL,
+
+    entname         character varying(128)
+                    COLLATE pg_catalog."default"
+                    NOT NULL,
+
+    entvalue        character varying(32768)
+                    COLLATE pg_catalog."default",
+
+    entvalue_jsonb  jsonb,
+
+    vnum            bigint NOT NULL,
+
+    validfrom       timestamp with time zone NOT NULL,
+    validto         timestamp with time zone,
+
+    dbaction        smallint NOT NULL,
+
+    dbactionuser    character varying(64)
+                    COLLATE pg_catalog."default"
+                    NOT NULL,
+
+    CONSTRAINT stsentity_pkey
+        PRIMARY KEY (oid),
+
+    CONSTRAINT stsentity_dbaction_check
+        CHECK (dbaction IN (1, 2, 3)),
+
+    -- Physical DELETE is not used by the versioning functions; they perform
+    -- logical deletes. ON DELETE CASCADE applies only if a stsresource row is
+    -- physically removed, in which case entity rows currently attached to that
+    -- resource OID are also physically removed.
+    CONSTRAINT fk_stsresource
+        FOREIGN KEY (resourceoid)
+        REFERENCES public.stsresource (oid)
+        MATCH SIMPLE
+        ON UPDATE NO ACTION
+        ON DELETE CASCADE
+)
+TABLESPACE pg_default;
+
+ALTER TABLE public.stsentity
+    OWNER TO postgres;
+
+-- Make the sequence lifecycle follow its dedicated table column.
+ALTER SEQUENCE public.stsentity_oid_seq
+    OWNED BY public.stsentity.oid;
+
+
+-- -----------------------------------------------------------------------------
+-- stsentity indexes
+-- -----------------------------------------------------------------------------
+
+-- Enforces entity version uniqueness within the current resource concept OID.
+--
+-- Because all entity rows are migrated whenever the resource OID changes, the
+-- complete entity version history continues to share the same resourceoid.
+CREATE UNIQUE INDEX stsentity_resourceoid_entname_vnum
+    ON public.stsentity USING btree
+    (
+        resourceoid ASC NULLS LAST,
+        entname COLLATE pg_catalog."default" ASC NULLS LAST,
+        vnum ASC NULLS LAST
+    )
+    TABLESPACE pg_default;
+
+
+-- Supports general entity history/current-version lookup.
+CREATE INDEX stsentity_resourceoid_entname_validto
+    ON public.stsentity USING btree
+    (
+        resourceoid ASC NULLS LAST,
+        entname COLLATE pg_catalog."default" ASC NULLS LAST,
+        validto DESC NULLS LAST
+    )
+    TABLESPACE pg_default;
+
+
+-- Database invariant: exactly zero or one CURRENT entity row may exist for an
+-- entity concept within a resource.
+--
+-- IMPORTANT:
+-- Do NOT filter dbaction = 3.
+--
+-- A logically deleted entity is still the current tombstone and must be closed
+-- before the entity can be recreated.
+CREATE UNIQUE INDEX idx_stsentity_resourceoid_entname_current
+    ON public.stsentity (resourceoid, entname)
+    WHERE validto IS NULL;
+
+
+-- =============================================================================
+-- Resource functions
+-- =============================================================================
+
+
+-- =============================================================================
+-- create_stsresource
+-- =============================================================================
+--
+-- Creates a new resource concept or reinstates a logically deleted resource.
+--
+-- Behaviour:
+--
+-- 1. Parse/validate the supplied JSON.
+-- 2. Look for the current resource row, INCLUDING a deleted tombstone.
+-- 3. If the current row is active, CREATE is rejected as a duplicate.
+-- 4. If the current row is deleted:
+--      * close the deleted version;
+--      * create the next active version;
+--      * move ALL entity history to the new current resource OID.
+-- 5. If no current row exists:
+--      * inspect the historical resource chain;
+--      * continue from MAX/latest vnum rather than resetting to version 1;
+--      * if historical entity rows point at the latest old resource OID, move
+--        them to the new resource OID.
+--
+-- The historical fallback in step 5 also provides safe recovery from an
+-- abnormal database state where history exists but no current row exists.
+CREATE OR REPLACE FUNCTION public.create_stsresource(
+    _dbactionuser character varying,
+    _resname      character varying,
+    _resdesc      character varying
+)
+RETURNS SETOF public.stsresource
+LANGUAGE plpgsql
+COST 100
+VOLATILE
+ROWS 1
+
+AS $BODY$
+DECLARE
+    __now              timestamptz := now();
+
+    -- Current resource, when one exists.
+    __resoid           bigint;
+    __vnum             bigint;
+    __dbaction         smallint;
+
+    -- Last historical resource when no current row exists.
+    __historical_oid   bigint;
+    __historical_vnum  bigint;
+
+    -- Version/OID of the new active row.
+    __newvnum          bigint;
+    __inserted_oid     bigint;
+
+    -- Parsed JSON.
+    __resdesc_jsonb    jsonb;
+BEGIN
+
+    -- -------------------------------------------------------------------------
+    -- Validate / parse resource JSON
+    -- -------------------------------------------------------------------------
+
+    BEGIN
+        __resdesc_jsonb := _resdesc::jsonb;
+
+    EXCEPTION
+        WHEN invalid_text_representation THEN
+            RAISE EXCEPTION
+                'Invalid JSON string: %',
+                _resdesc
+                USING ERRCODE = 'invalid_text_representation';
+    END;
+
+
+    -- -------------------------------------------------------------------------
+    -- Resolve and lock the current resource, including deleted tombstones.
+    --
+    -- The lock serializes update/delete/recreate operations for an existing
+    -- resource concept.
+    -- -------------------------------------------------------------------------
+
+    BEGIN
+        SELECT
+            r.oid,
+            r.vnum,
+            r.dbaction
+        INTO STRICT
+            __resoid,
+            __vnum,
+            __dbaction
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+          AND r.validto IS NULL
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            __resoid := NULL;
+            __vnum := NULL;
+            __dbaction := NULL;
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsresource records for resource %',
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- -------------------------------------------------------------------------
+    -- A current resource exists.
+    -- -------------------------------------------------------------------------
+
+    IF __resoid IS NOT NULL THEN
+
+        -- An active resource already exists, so CREATE is invalid.
+        IF __dbaction != 3 THEN
+            RAISE
+                'Duplicate resname within stsresource: %',
+                _resname
+                USING ERRCODE = 'unique_violation';
+        END IF;
+
+
+        -- ---------------------------------------------------------------------
+        -- Reinstating a deleted resource concept.
+        --
+        -- Close the delete tombstone and continue the resource version chain.
+        -- ---------------------------------------------------------------------
+
+        UPDATE public.stsresource
+        SET validto = __now
+        WHERE oid = __resoid;
+
+        __newvnum := __vnum + 1;
+
+        INSERT INTO public.stsresource(
+            resname,
+            resdesc,
+            resdesc_jsonb,
+            vnum,
+            dbaction,
+            dbactionuser,
+            validfrom
+        )
+        VALUES (
+            _resname,
+            _resdesc,
+            __resdesc_jsonb,
+            __newvnum,
+            1,
+            _dbactionuser,
+            __now
+        )
+        RETURNING oid
+        INTO __inserted_oid;
+
+
+        -- ---------------------------------------------------------------------
+        -- RESOURCE-CONCEPT SEMANTICS
+        --
+        -- The entities belong to the resource concept, not to the deleted
+        -- resource version row. Move the complete entity history to the newly
+        -- reinstated resource OID.
+        -- ---------------------------------------------------------------------
+
+        UPDATE public.stsentity
+        SET resourceoid = __inserted_oid
+        WHERE resourceoid = __resoid;
+
+
+    ELSE
+
+        -- ---------------------------------------------------------------------
+        -- No current row exists.
+        --
+        -- Normally this is the first creation and there is no history.
+        --
+        -- If history exists without a current row, lock the latest historical
+        -- version and continue its version sequence instead of incorrectly
+        -- resetting to version 1.
+        -- ---------------------------------------------------------------------
+
+        SELECT
+            r.oid,
+            r.vnum
+        INTO
+            __historical_oid,
+            __historical_vnum
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+        ORDER BY r.vnum DESC
+        LIMIT 1
+        FOR UPDATE;
+
+        __newvnum := COALESCE(__historical_vnum, 0) + 1;
+
+
+        -- Create the new active resource version.
+        INSERT INTO public.stsresource(
+            resname,
+            resdesc,
+            resdesc_jsonb,
+            vnum,
+            dbaction,
+            dbactionuser,
+            validfrom
+        )
+        VALUES (
+            _resname,
+            _resdesc,
+            __resdesc_jsonb,
+            __newvnum,
+            1,
+            _dbactionuser,
+            __now
+        )
+        RETURNING oid
+        INTO __inserted_oid;
+
+
+        -- If this was recovery from historical data with no current row,
+        -- preserve the resource-concept ownership of any entity history.
+        IF __historical_oid IS NOT NULL THEN
+            UPDATE public.stsentity
+            SET resourceoid = __inserted_oid
+            WHERE resourceoid = __historical_oid;
+        END IF;
+
+    END IF;
+
+
+    -- -------------------------------------------------------------------------
+    -- Return the newly created/reinstated resource version.
+    -- -------------------------------------------------------------------------
+
+    RETURN QUERY
+    SELECT *
+    FROM public.stsresource
+    WHERE oid = __inserted_oid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.create_stsresource(
+    character varying,
+    character varying,
+    character varying
+)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- update_stsresource
+-- =============================================================================
+--
+-- Updates a caller-specified current resource version.
+--
+-- The supplied version acts as an optimistic-concurrency requirement:
+-- the resource must still be current, active, and exactly _resvnum.
+--
+-- Creating the next resource version changes the current resource OID, so all
+-- entity history is moved to the new OID to preserve resource-concept
+-- ownership.
+CREATE OR REPLACE FUNCTION public.update_stsresource(
+    _dbactionuser character varying,
+    _resname      character varying,
+    _resvnum      bigint,
+    _resdesc      character varying
+)
+RETURNS SETOF public.stsresource
+LANGUAGE plpgsql
+COST 100
+VOLATILE
+ROWS 1
+
+AS $BODY$
+DECLARE
+    __now           timestamptz := now();
+    __resoid        bigint;
+    __newresoid     bigint;
+    __resdesc_jsonb jsonb;
+BEGIN
+
+    -- Validate / parse resource JSON.
+    BEGIN
+        __resdesc_jsonb := _resdesc::jsonb;
+
+    EXCEPTION
+        WHEN invalid_text_representation THEN
+            RAISE EXCEPTION
+                'Invalid JSON string: %',
+                _resdesc
+                USING ERRCODE = 'invalid_text_representation';
+    END;
+
+
+    -- Resolve and lock the requested current, non-deleted resource version.
+    BEGIN
+        SELECT
+            r.oid
+        INTO STRICT
+            __resoid
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+          AND r.vnum = _resvnum
+          AND r.validto IS NULL
+          AND r.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Resource % version % not found, not current, or deleted',
+                _resname,
+                _resvnum
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsresource records for resource % version %',
+                _resname,
+                _resvnum
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Close the previous active resource version.
+    UPDATE public.stsresource
+    SET validto = __now
+    WHERE oid = __resoid;
+
+
+    -- Create the next active resource version.
+    INSERT INTO public.stsresource(
+        resname,
+        resdesc,
+        resdesc_jsonb,
+        vnum,
+        dbaction,
+        dbactionuser,
+        validfrom
+    )
+    VALUES (
+        _resname,
+        _resdesc,
+        __resdesc_jsonb,
+        _resvnum + 1,
+        2,
+        _dbactionuser,
+        __now
+    )
+    RETURNING oid
+    INTO __newresoid;
+
+
+    -- Move all entity history to the new current resource OID.
+    UPDATE public.stsentity
+    SET resourceoid = __newresoid
+    WHERE resourceoid = __resoid;
+
+
+    -- Return the new resource version.
+    RETURN QUERY
+    SELECT *
+    FROM public.stsresource
+    WHERE oid = __newresoid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.update_stsresource(
+    character varying,
+    character varying,
+    bigint,
+    character varying
+)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- update_stsresource_latest
+-- =============================================================================
+--
+-- Updates the current active resource without requiring the caller to supply
+-- its version number.
+--
+-- oid and vnum are resolved in one locked query to avoid the duplicate lookups
+-- used by the original implementation.
+CREATE OR REPLACE FUNCTION public.update_stsresource_latest(
+    _dbactionuser character varying,
+    _resname      character varying,
+    _resdesc      character varying
+)
+RETURNS SETOF public.stsresource
+LANGUAGE plpgsql
+COST 100
+VOLATILE
+ROWS 1
+
+AS $BODY$
+DECLARE
+    __now           timestamptz := now();
+    __resoid        bigint;
+    __resvnum       bigint;
+    __newresoid     bigint;
+    __resdesc_jsonb jsonb;
+BEGIN
+
+    -- Validate / parse resource JSON.
+    BEGIN
+        __resdesc_jsonb := _resdesc::jsonb;
+
+    EXCEPTION
+        WHEN invalid_text_representation THEN
+            RAISE EXCEPTION
+                'Invalid JSON string: %',
+                _resdesc
+                USING ERRCODE = 'invalid_text_representation';
+    END;
+
+
+    -- Resolve and lock the current active resource in one operation.
+    BEGIN
+        SELECT
+            r.oid,
+            r.vnum
+        INTO STRICT
+            __resoid,
+            __resvnum
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+          AND r.validto IS NULL
+          AND r.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Resource % not found, not current, or deleted',
+                _resname
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsresource records for resource %',
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Close the previous active resource version.
+    UPDATE public.stsresource
+    SET validto = __now
+    WHERE oid = __resoid;
+
+
+    -- Create the next active resource version.
+    INSERT INTO public.stsresource(
+        resname,
+        resdesc,
+        resdesc_jsonb,
+        vnum,
+        dbaction,
+        dbactionuser,
+        validfrom
+    )
+    VALUES (
+        _resname,
+        _resdesc,
+        __resdesc_jsonb,
+        __resvnum + 1,
+        2,
+        _dbactionuser,
+        __now
+    )
+    RETURNING oid
+    INTO __newresoid;
+
+
+    -- Preserve resource-concept ownership for all entity history.
+    UPDATE public.stsentity
+    SET resourceoid = __newresoid
+    WHERE resourceoid = __resoid;
+
+
+    -- Return the new resource version.
+    RETURN QUERY
+    SELECT *
+    FROM public.stsresource
+    WHERE oid = __newresoid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.update_stsresource_latest(
+    character varying,
+    character varying,
+    character varying
+)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- delete_stsresource
+-- =============================================================================
+--
+-- Logically deletes a caller-specified current resource version.
+--
+-- Delete is versioned: the active row is closed and a new dbaction=3 tombstone
+-- becomes the current resource version.
+--
+-- Entity rows are NOT individually deleted. Their complete history is moved to
+-- the new resource tombstone OID. If the resource is later recreated, those
+-- same rows are moved again to the reinstated active resource OID.
+CREATE OR REPLACE FUNCTION public.delete_stsresource(
+    _dbactionuser character varying,
+    _resname      character varying,
+    _resvnum      bigint
+)
+RETURNS SETOF public.stsresource
+LANGUAGE plpgsql
+COST 100
+VOLATILE
+ROWS 1
+
+AS $BODY$
+DECLARE
+    __now       timestamptz := now();
+    __resoid    bigint;
+    __newresoid bigint;
+BEGIN
+
+    -- Resolve and lock the requested current active resource version.
+    BEGIN
+        SELECT
+            r.oid
+        INTO STRICT
+            __resoid
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+          AND r.vnum = _resvnum
+          AND r.validto IS NULL
+          AND r.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Resource % version % not found, not current, or deleted',
+                _resname,
+                _resvnum
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsresource records for resource % version %',
+                _resname,
+                _resvnum
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Close the current active resource version.
+    UPDATE public.stsresource
+    SET validto = __now
+    WHERE oid = __resoid;
+
+
+    -- Create the delete tombstone.
+    --
+    -- Copy resdesc_jsonb directly rather than reparsing resdesc text.
+    INSERT INTO public.stsresource(
+        resname,
+        resdesc,
+        resdesc_jsonb,
+        vnum,
+        dbaction,
+        dbactionuser,
+        validfrom
+    )
+    SELECT
+        r.resname,
+        r.resdesc,
+        r.resdesc_jsonb,
+        _resvnum + 1,
+        3,
+        _dbactionuser,
+        __now
+    FROM public.stsresource r
+    WHERE r.oid = __resoid
+    RETURNING oid
+    INTO __newresoid;
+
+
+    -- Preserve the entity history under the current resource tombstone OID.
+    UPDATE public.stsentity
+    SET resourceoid = __newresoid
+    WHERE resourceoid = __resoid;
+
+
+    -- Return the delete tombstone.
+    RETURN QUERY
+    SELECT *
+    FROM public.stsresource
+    WHERE oid = __newresoid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.delete_stsresource(
+    character varying,
+    character varying,
+    bigint
+)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- delete_stsresource_latest
+-- =============================================================================
+--
+-- Logically deletes the current active resource without requiring the caller to
+-- provide its version number.
+--
+-- The current OID and version are resolved together and locked in one query.
+CREATE OR REPLACE FUNCTION public.delete_stsresource_latest(
+    _dbactionuser character varying,
+    _resname      character varying
+)
+RETURNS SETOF public.stsresource
+LANGUAGE plpgsql
+COST 100
+VOLATILE
+ROWS 1
+
+AS $BODY$
+DECLARE
+    __now       timestamptz := now();
+    __resoid    bigint;
+    __resvnum   bigint;
+    __newresoid bigint;
+BEGIN
+
+    -- Resolve and lock the current active resource.
+    BEGIN
+        SELECT
+            r.oid,
+            r.vnum
+        INTO STRICT
+            __resoid,
+            __resvnum
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+          AND r.validto IS NULL
+          AND r.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Resource % not found, not current, or deleted',
+                _resname
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsresource records for resource %',
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Close the current active resource version.
+    UPDATE public.stsresource
+    SET validto = __now
+    WHERE oid = __resoid;
+
+
+    -- Create the delete tombstone.
+    --
+    -- The original implementation accidentally omitted resdesc_jsonb from the
+    -- SELECT even though it was present in the INSERT column list. This version
+    -- copies the already parsed JSONB value correctly.
+    INSERT INTO public.stsresource(
+        resname,
+        resdesc,
+        resdesc_jsonb,
+        vnum,
+        dbaction,
+        dbactionuser,
+        validfrom
+    )
+    SELECT
+        r.resname,
+        r.resdesc,
+        r.resdesc_jsonb,
+        __resvnum + 1,
+        3,
+        _dbactionuser,
+        __now
+    FROM public.stsresource r
+    WHERE r.oid = __resoid
+    RETURNING oid
+    INTO __newresoid;
+
+
+    -- Preserve the entity history under the current resource tombstone OID.
+    UPDATE public.stsentity
+    SET resourceoid = __newresoid
+    WHERE resourceoid = __resoid;
+
+
+    -- Return the delete tombstone.
+    RETURN QUERY
+    SELECT *
+    FROM public.stsresource
+    WHERE oid = __newresoid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.delete_stsresource_latest(
+    character varying,
+    character varying
+)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- Entity functions
+-- =============================================================================
+
+
+-- =============================================================================
+-- create_stsentity
+-- =============================================================================
+--
+-- Creates an entity against a caller-specified current resource version.
+--
+-- A deleted entity is still the current entity tombstone. CREATE against a
+-- deleted entity closes that tombstone and continues the entity version chain.
+--
+-- The current resource row is locked first. This prevents the resource from
+-- changing OID while the entity operation is in progress.
+CREATE OR REPLACE FUNCTION public.create_stsentity(
+    _dbactionuser character varying,
+    _resname      character varying,
+    _resvnum      bigint,
+    _entname      character varying,
+    _entvalue     character varying
+)
+RETURNS SETOF public.stsentity
+LANGUAGE plpgsql
+COST 100
+VOLATILE
+ROWS 1
+
+AS $BODY$
+DECLARE
+    __now              timestamptz := now();
+
+    -- Current resource.
+    __resoid           bigint;
+
+    -- Current entity, if one exists.
+    __entoid           bigint;
+    __entvnum          bigint;
+    __entdbaction      smallint;
+
+    -- Version/OID for the new active entity.
+    __newvnum          bigint;
+    __inserted_oid     bigint;
+
+    -- Parsed JSON.
+    __entvalue_jsonb   jsonb;
+BEGIN
+
+    -- -------------------------------------------------------------------------
+    -- Validate / parse entity JSON.
+    -- -------------------------------------------------------------------------
+
+    BEGIN
+        __entvalue_jsonb := _entvalue::jsonb;
+
+    EXCEPTION
+        WHEN invalid_text_representation THEN
+            RAISE EXCEPTION
+                'Invalid JSON string: %',
+                _entvalue
+                USING ERRCODE = 'invalid_text_representation';
+    END;
+
+
+    -- -------------------------------------------------------------------------
+    -- Resolve and lock the requested current, non-deleted resource version.
+    --
+    -- Locking the resource prevents a concurrent resource update/delete from
+    -- changing resourceoid while this entity transaction is operating.
+    -- -------------------------------------------------------------------------
+
+    BEGIN
+        SELECT
+            r.oid
+        INTO STRICT
+            __resoid
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+          AND r.vnum = _resvnum
+          AND r.validto IS NULL
+          AND r.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Resource % version % not found, not current, or deleted',
+                _resname,
+                _resvnum
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsresource records for resource % version %',
+                _resname,
+                _resvnum
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- -------------------------------------------------------------------------
+    -- Find and lock the current entity.
+    --
+    -- IMPORTANT:
+    -- Do NOT exclude dbaction = 3.
+    --
+    -- A logically deleted entity remains the current entity version and must be
+    -- closed before it can be recreated.
+    -- -------------------------------------------------------------------------
+
+    BEGIN
+        SELECT
+            e.oid,
+            e.vnum,
+            e.dbaction
+        INTO STRICT
+            __entoid,
+            __entvnum,
+            __entdbaction
+        FROM public.stsentity e
+        WHERE e.resourceoid = __resoid
+          AND e.entname = _entname
+          AND e.validto IS NULL
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            __entoid := NULL;
+            __entvnum := NULL;
+            __entdbaction := NULL;
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsentity records for entity % within resource %',
+                _entname,
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- -------------------------------------------------------------------------
+    -- A current entity exists.
+    -- -------------------------------------------------------------------------
+
+    IF __entoid IS NOT NULL THEN
+
+        -- Active current entity: CREATE is a duplicate.
+        IF __entdbaction != 3 THEN
+            RAISE
+                'Duplicate entname % within stsresource %',
+                _entname,
+                _resname
+                USING ERRCODE = 'unique_violation';
+        END IF;
+
+
+        -- Deleted current entity: close the tombstone and continue versioning.
+        UPDATE public.stsentity
+        SET validto = __now
+        WHERE oid = __entoid;
+
+        __newvnum := __entvnum + 1;
+
+    ELSE
+
+        -- ---------------------------------------------------------------------
+        -- No current entity exists.
+        --
+        -- Normally this is the first creation, producing version 1.
+        --
+        -- MAX(vnum) also protects against an abnormal history in which previous
+        -- versions exist but no entity row currently has validto IS NULL.
+        -- ---------------------------------------------------------------------
+
+        SELECT
+            COALESCE(MAX(e.vnum), 0) + 1
+        INTO
+            __newvnum
+        FROM public.stsentity e
+        WHERE e.resourceoid = __resoid
+          AND e.entname = _entname;
+
+    END IF;
+
+
+    -- Create the new active entity version.
+    INSERT INTO public.stsentity(
+        resourceoid,
+        entname,
+        entvalue,
+        entvalue_jsonb,
+        vnum,
+        dbaction,
+        dbactionuser,
+        validfrom
+    )
+    VALUES (
+        __resoid,
+        _entname,
+        _entvalue,
+        __entvalue_jsonb,
+        __newvnum,
+        1,
+        _dbactionuser,
+        __now
+    )
+    RETURNING oid
+    INTO __inserted_oid;
+
+
+    -- Return the newly created/recreated entity.
+    RETURN QUERY
+    SELECT *
+    FROM public.stsentity
+    WHERE oid = __inserted_oid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.create_stsentity(
+    character varying,
+    character varying,
+    bigint,
+    character varying,
+    character varying
+)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- create_stsentity_latest
+-- =============================================================================
+--
+-- Creates an entity against the latest/current active resource version.
+--
+-- This is identical in entity semantics to create_stsentity, except the caller
+-- does not supply the resource version.
+CREATE OR REPLACE FUNCTION public.create_stsentity_latest(
+    _dbactionuser character varying,
+    _resname      character varying,
+    _entname      character varying,
+    _entvalue     character varying
+)
+RETURNS SETOF public.stsentity
+LANGUAGE plpgsql
+COST 100
+VOLATILE
+ROWS 1
+
+AS $BODY$
+DECLARE
+    __now              timestamptz := now();
+
+    __resoid           bigint;
+
+    __entoid           bigint;
+    __entvnum          bigint;
+    __entdbaction      smallint;
+
+    __newvnum          bigint;
+    __inserted_oid     bigint;
+
+    __entvalue_jsonb   jsonb;
+BEGIN
+
+    -- Validate / parse entity JSON.
+    BEGIN
+        __entvalue_jsonb := _entvalue::jsonb;
+
+    EXCEPTION
+        WHEN invalid_text_representation THEN
+            RAISE EXCEPTION
+                'Invalid JSON string: %',
+                _entvalue
+                USING ERRCODE = 'invalid_text_representation';
+    END;
+
+
+    -- Resolve and lock the current active resource.
+    BEGIN
+        SELECT
+            r.oid
+        INTO STRICT
+            __resoid
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+          AND r.validto IS NULL
+          AND r.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Resource % not found, not current, or deleted',
+                _resname
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsresource records for resource %',
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Resolve and lock the current entity, including a deleted tombstone.
+    BEGIN
+        SELECT
+            e.oid,
+            e.vnum,
+            e.dbaction
+        INTO STRICT
+            __entoid,
+            __entvnum,
+            __entdbaction
+        FROM public.stsentity e
+        WHERE e.resourceoid = __resoid
+          AND e.entname = _entname
+          AND e.validto IS NULL
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            __entoid := NULL;
+            __entvnum := NULL;
+            __entdbaction := NULL;
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsentity records for entity % within resource %',
+                _entname,
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Current entity exists.
+    IF __entoid IS NOT NULL THEN
+
+        -- Active entity already exists.
+        IF __entdbaction != 3 THEN
+            RAISE
+                'Duplicate entname % within stsresource %',
+                _entname,
+                _resname
+                USING ERRCODE = 'unique_violation';
+        END IF;
+
+        -- Recreate the deleted entity by closing its tombstone.
+        UPDATE public.stsentity
+        SET validto = __now
+        WHERE oid = __entoid;
+
+        __newvnum := __entvnum + 1;
+
+    ELSE
+
+        -- First creation, or recovery from history with no current row.
+        SELECT
+            COALESCE(MAX(e.vnum), 0) + 1
+        INTO
+            __newvnum
+        FROM public.stsentity e
+        WHERE e.resourceoid = __resoid
+          AND e.entname = _entname;
+
+    END IF;
+
+
+    -- Create the new active entity version.
+    INSERT INTO public.stsentity(
+        resourceoid,
+        entname,
+        entvalue,
+        entvalue_jsonb,
+        vnum,
+        dbaction,
+        dbactionuser,
+        validfrom
+    )
+    VALUES (
+        __resoid,
+        _entname,
+        _entvalue,
+        __entvalue_jsonb,
+        __newvnum,
+        1,
+        _dbactionuser,
+        __now
+    )
+    RETURNING oid
+    INTO __inserted_oid;
+
+
+    -- Return the new entity version.
+    RETURN QUERY
+    SELECT *
+    FROM public.stsentity
+    WHERE oid = __inserted_oid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.create_stsentity_latest(
+    character varying,
+    character varying,
+    character varying,
+    character varying
+)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- update_stsentity
+-- =============================================================================
+--
+-- Updates a caller-specified current entity version under a caller-specified
+-- current resource version.
+--
+-- Both version arguments therefore act as optimistic-concurrency requirements.
+CREATE OR REPLACE FUNCTION public.update_stsentity(
+    _dbactionuser character varying,
+    _resname      character varying,
+    _resvnum      bigint,
+    _entname      character varying,
+    _entvnum      bigint,
+    _entvalue     character varying
+)
+RETURNS SETOF public.stsentity
+LANGUAGE plpgsql
+COST 100
+VOLATILE
+ROWS 1
+
+AS $BODY$
+DECLARE
+    __now              timestamptz := now();
+    __resoid           bigint;
+    __entoid           bigint;
+    __inserted_oid     bigint;
+    __entvalue_jsonb   jsonb;
+BEGIN
+
+    -- Validate / parse entity JSON.
+    BEGIN
+        __entvalue_jsonb := _entvalue::jsonb;
+
+    EXCEPTION
+        WHEN invalid_text_representation THEN
+            RAISE EXCEPTION
+                'Invalid JSON string: %',
+                _entvalue
+                USING ERRCODE = 'invalid_text_representation';
+    END;
+
+
+    -- Resolve and lock the requested current active resource version.
+    BEGIN
+        SELECT
+            r.oid
+        INTO STRICT
+            __resoid
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+          AND r.vnum = _resvnum
+          AND r.validto IS NULL
+          AND r.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Resource % version % not found, not current, or deleted',
+                _resname,
+                _resvnum
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsresource records for resource % version %',
+                _resname,
+                _resvnum
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Resolve and lock the requested current active entity version.
+    BEGIN
+        SELECT
+            e.oid
+        INTO STRICT
+            __entoid
+        FROM public.stsentity e
+        WHERE e.resourceoid = __resoid
+          AND e.entname = _entname
+          AND e.vnum = _entvnum
+          AND e.validto IS NULL
+          AND e.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Entity % version % not found, not current, or deleted within resource %',
+                _entname,
+                _entvnum,
+                _resname
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsentity records for entity % version % within resource %',
+                _entname,
+                _entvnum,
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Close the previous entity version.
+    UPDATE public.stsentity
+    SET validto = __now
+    WHERE oid = __entoid;
+
+
+    -- Create the next active entity version.
+    INSERT INTO public.stsentity(
+        resourceoid,
+        entname,
+        entvalue,
+        entvalue_jsonb,
+        vnum,
+        dbaction,
+        dbactionuser,
+        validfrom
+    )
+    VALUES (
+        __resoid,
+        _entname,
+        _entvalue,
+        __entvalue_jsonb,
+        _entvnum + 1,
+        2,
+        _dbactionuser,
+        __now
+    )
+    RETURNING oid
+    INTO __inserted_oid;
+
+
+    -- Return the new entity version.
+    RETURN QUERY
+    SELECT *
+    FROM public.stsentity
+    WHERE oid = __inserted_oid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.update_stsentity(
+    character varying,
+    character varying,
+    bigint,
+    character varying,
+    bigint,
+    character varying
+)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- update_stsentity_latest
+-- =============================================================================
+--
+-- Updates the current active entity under the current active resource.
+--
+-- The current entity OID and version are resolved together in one locked query.
+CREATE OR REPLACE FUNCTION public.update_stsentity_latest(
+    _dbactionuser character varying,
+    _resname      character varying,
+    _entname      character varying,
+    _entvalue     character varying
+)
+RETURNS SETOF public.stsentity
+LANGUAGE plpgsql
+COST 100
+VOLATILE
+ROWS 1
+
+AS $BODY$
+DECLARE
+    __now              timestamptz := now();
+    __resoid           bigint;
+    __entoid           bigint;
+    __entvnum          bigint;
+    __inserted_oid     bigint;
+    __entvalue_jsonb   jsonb;
+BEGIN
+
+    -- Validate / parse entity JSON.
+    BEGIN
+        __entvalue_jsonb := _entvalue::jsonb;
+
+    EXCEPTION
+        WHEN invalid_text_representation THEN
+            RAISE EXCEPTION
+                'Invalid JSON string: %',
+                _entvalue
+                USING ERRCODE = 'invalid_text_representation';
+    END;
+
+
+    -- Resolve and lock the current active resource.
+    BEGIN
+        SELECT
+            r.oid
+        INTO STRICT
+            __resoid
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+          AND r.validto IS NULL
+          AND r.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Resource % not found, not current, or deleted',
+                _resname
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsresource records for resource %',
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Resolve and lock the current active entity and its version.
+    BEGIN
+        SELECT
+            e.oid,
+            e.vnum
+        INTO STRICT
+            __entoid,
+            __entvnum
+        FROM public.stsentity e
+        WHERE e.resourceoid = __resoid
+          AND e.entname = _entname
+          AND e.validto IS NULL
+          AND e.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Entity % not found, not current, or deleted within resource %',
+                _entname,
+                _resname
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsentity records for entity % within resource %',
+                _entname,
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Close the previous entity version.
+    UPDATE public.stsentity
+    SET validto = __now
+    WHERE oid = __entoid;
+
+
+    -- Create the next active entity version.
+    INSERT INTO public.stsentity(
+        resourceoid,
+        entname,
+        entvalue,
+        entvalue_jsonb,
+        vnum,
+        dbaction,
+        dbactionuser,
+        validfrom
+    )
+    VALUES (
+        __resoid,
+        _entname,
+        _entvalue,
+        __entvalue_jsonb,
+        __entvnum + 1,
+        2,
+        _dbactionuser,
+        __now
+    )
+    RETURNING oid
+    INTO __inserted_oid;
+
+
+    -- Return the new entity version.
+    RETURN QUERY
+    SELECT *
+    FROM public.stsentity
+    WHERE oid = __inserted_oid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.update_stsentity_latest(
+    character varying,
+    character varying,
+    character varying,
+    character varying
+)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- delete_stsentity
+-- =============================================================================
+--
+-- Logically deletes a caller-specified current active entity version.
+--
+-- Delete closes the active entity version and creates a dbaction=3 tombstone
+-- as the next/current version.
+CREATE OR REPLACE FUNCTION public.delete_stsentity(
+    _dbactionuser character varying,
+    _resname      character varying,
+    _resvnum      bigint,
+    _entname      character varying,
+    _entvnum      bigint
+)
+RETURNS SETOF public.stsentity
+LANGUAGE plpgsql
+COST 100
+VOLATILE
+ROWS 1
+
+AS $BODY$
+DECLARE
+    __now          timestamptz := now();
+    __resoid       bigint;
+    __entoid       bigint;
+    __inserted_oid bigint;
+BEGIN
+
+    -- Resolve and lock the requested current active resource version.
+    BEGIN
+        SELECT
+            r.oid
+        INTO STRICT
+            __resoid
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+          AND r.vnum = _resvnum
+          AND r.validto IS NULL
+          AND r.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Resource % version % not found, not current, or deleted',
+                _resname,
+                _resvnum
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsresource records for resource % version %',
+                _resname,
+                _resvnum
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Resolve and lock the requested current active entity version.
+    BEGIN
+        SELECT
+            e.oid
+        INTO STRICT
+            __entoid
+        FROM public.stsentity e
+        WHERE e.resourceoid = __resoid
+          AND e.entname = _entname
+          AND e.vnum = _entvnum
+          AND e.validto IS NULL
+          AND e.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Entity % version % not found, not current, or deleted within resource %',
+                _entname,
+                _entvnum,
+                _resname
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsentity records for entity % version % within resource %',
+                _entname,
+                _entvnum,
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Close the previous active entity version.
+    UPDATE public.stsentity
+    SET validto = __now
+    WHERE oid = __entoid;
+
+
+    -- Create the delete tombstone.
+    --
+    -- Copy entvalue_jsonb directly rather than reparsing entvalue text.
+    INSERT INTO public.stsentity(
+        resourceoid,
+        entname,
+        entvalue,
+        entvalue_jsonb,
+        vnum,
+        dbaction,
+        dbactionuser,
+        validfrom
+    )
+    SELECT
+        __resoid,
+        e.entname,
+        e.entvalue,
+        e.entvalue_jsonb,
+        _entvnum + 1,
+        3,
+        _dbactionuser,
+        __now
+    FROM public.stsentity e
+    WHERE e.oid = __entoid
+    RETURNING oid
+    INTO __inserted_oid;
+
+
+    -- Return the delete tombstone.
+    RETURN QUERY
+    SELECT *
+    FROM public.stsentity
+    WHERE oid = __inserted_oid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.delete_stsentity(
+    character varying,
+    character varying,
+    bigint,
+    character varying,
+    bigint
+)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- delete_stsentity_latest
+-- =============================================================================
+--
+-- Logically deletes the current active entity under the current active resource
+-- without requiring the caller to provide either version number.
+CREATE OR REPLACE FUNCTION public.delete_stsentity_latest(
+    _dbactionuser character varying,
+    _resname      character varying,
+    _entname      character varying
+)
+RETURNS SETOF public.stsentity
+LANGUAGE plpgsql
+COST 100
+VOLATILE
+ROWS 1
+
+AS $BODY$
+DECLARE
+    __now          timestamptz := now();
+    __resoid       bigint;
+    __entoid       bigint;
+    __entvnum      bigint;
+    __inserted_oid bigint;
+BEGIN
+
+    -- Resolve and lock the current active resource.
+    BEGIN
+        SELECT
+            r.oid
+        INTO STRICT
+            __resoid
+        FROM public.stsresource r
+        WHERE r.resname = _resname
+          AND r.validto IS NULL
+          AND r.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Resource % not found, not current, or deleted',
+                _resname
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsresource records for resource %',
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Resolve and lock the current active entity and its version.
+    BEGIN
+        SELECT
+            e.oid,
+            e.vnum
+        INTO STRICT
+            __entoid,
+            __entvnum
+        FROM public.stsentity e
+        WHERE e.resourceoid = __resoid
+          AND e.entname = _entname
+          AND e.validto IS NULL
+          AND e.dbaction != 3
+        FOR UPDATE;
+
+    EXCEPTION
+
+        WHEN no_data_found THEN
+            RAISE
+                'Entity % not found, not current, or deleted within resource %',
+                _entname,
+                _resname
+                USING ERRCODE = 'no_data_found';
+
+        WHEN too_many_rows THEN
+            RAISE
+                'Too many current stsentity records for entity % within resource %',
+                _entname,
+                _resname
+                USING ERRCODE = 'cardinality_violation';
+
+    END;
+
+
+    -- Close the previous active entity version.
+    UPDATE public.stsentity
+    SET validto = __now
+    WHERE oid = __entoid;
+
+
+    -- Create the delete tombstone.
+    INSERT INTO public.stsentity(
+        resourceoid,
+        entname,
+        entvalue,
+        entvalue_jsonb,
+        vnum,
+        dbaction,
+        dbactionuser,
+        validfrom
+    )
+    SELECT
+        __resoid,
+        e.entname,
+        e.entvalue,
+        e.entvalue_jsonb,
+        __entvnum + 1,
+        3,
+        _dbactionuser,
+        __now
+    FROM public.stsentity e
+    WHERE e.oid = __entoid
+    RETURNING oid
+    INTO __inserted_oid;
+
+
+    -- Return the delete tombstone.
+    RETURN QUERY
+    SELECT *
+    FROM public.stsentity
+    WHERE oid = __inserted_oid;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.delete_stsentity_latest(
+    character varying,
+    character varying,
+    character varying
+)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- Count functions
+-- =============================================================================
+
+
+-- =============================================================================
+-- count_stsresource
+-- =============================================================================
+--
+-- Counts stsresource rows.
+--
+-- _valid_records = false
+--     Count every physical stsresource row, including all historical versions
+--     and delete tombstones.
+--
+-- _valid_records = true
+--     Count only current ACTIVE resource concepts.
+--
+--     A delete tombstone has validto IS NULL but dbaction = 3, so both
+--     predicates are required. Testing validto alone would incorrectly count
+--     logically deleted resources as valid.
+--
+-- This function performs no writes and is therefore STABLE rather than
+-- VOLATILE.
+CREATE OR REPLACE FUNCTION public.count_stsresource(
+    _valid_records boolean DEFAULT false
+)
+RETURNS TABLE (count bigint)
+LANGUAGE plpgsql
+COST 100
+STABLE
+ROWS 1
+
+AS $BODY$
+BEGIN
+
+    IF _valid_records THEN
+
+        RETURN QUERY
+        SELECT
+            COUNT(*)::bigint
+        FROM public.stsresource r
+        WHERE r.validto IS NULL
+          AND r.dbaction != 3;
+
+    ELSE
+
+        RETURN QUERY
+        SELECT
+            COUNT(*)::bigint
+        FROM public.stsresource r;
+
+    END IF;
+
+END;
+$BODY$;
+
+ALTER FUNCTION public.count_stsresource(boolean)
+OWNER TO postgres;
+
+
+-- =============================================================================
+-- End of stsrest01 generic resource/entity schema
+-- =============================================================================