Merge branch 'main' of https://git.stella-ops.org/stella-ops.org/git.stella-ops.org

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Migrations/002_hlc_queue_chain.sql

@@ -1,177 +1,171 @@
--- HLC Queue Chain: Hybrid Logical Clock Ordering with Cryptographic Sequence Proofs
--- SPRINT_20260105_002_002_SCHEDULER: SQC-002, SQC-003, SQC-004
---
--- Adds HLC-based ordering with hash chain at enqueue time for audit-safe job queue ordering.
--- See: Product Advisory "Audit-safe job queue ordering using monotonic timestamps"
-
-BEGIN;
+-- -----------------------------------------------------------------------------
+-- 002_hlc_queue_chain.sql
+-- Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
+-- Tasks: SQC-002, SQC-003, SQC-004
+-- Description: HLC-ordered scheduler queue with cryptographic chain linking
+-- -----------------------------------------------------------------------------
 
 -- ============================================================================
--- SECTION 1: Scheduler Log Table (SQC-002)
+-- SQC-002: scheduler.scheduler_log - HLC-ordered, chain-linked jobs
 -- ============================================================================
--- HLC-ordered, chain-linked job entries. This is the authoritative order.
--- Jobs are linked via: link_i = Hash(link_{i-1} || job_id || t_hlc || payload_hash)
 
 CREATE TABLE IF NOT EXISTS scheduler.scheduler_log (
-    seq_bigint      BIGSERIAL PRIMARY KEY,          -- Storage order (not authoritative)
+    -- Storage order (BIGSERIAL for monotonic insertion, not authoritative for ordering)
+    seq_bigint      BIGSERIAL PRIMARY KEY,
+
+    -- Tenant isolation
     tenant_id       TEXT NOT NULL,
-    t_hlc           TEXT NOT NULL,                  -- HLC timestamp: "0001704067200000-node-1-000042"
-    partition_key   TEXT NOT NULL DEFAULT '',       -- Optional queue partition
+
+    -- HLC timestamp: "1704067200000-scheduler-east-1-000042"
+    -- This is the authoritative ordering key
+    t_hlc           TEXT NOT NULL,
+
+    -- Optional queue partition for parallel processing
+    partition_key   TEXT DEFAULT '',
+
+    -- Job identifier (deterministic from payload using GUID v5)
     job_id          UUID NOT NULL,
-    payload_hash    BYTEA NOT NULL,                 -- SHA-256 of canonical payload JSON
-    prev_link       BYTEA,                          -- Previous chain link (null for first)
-    link            BYTEA NOT NULL,                 -- Hash(prev_link || job_id || t_hlc || payload_hash)
+
+    -- SHA-256 of canonical JSON payload (32 bytes)
+    payload_hash    BYTEA NOT NULL CHECK (octet_length(payload_hash) = 32),
+
+    -- Previous chain link (null for first entry in partition)
+    prev_link       BYTEA CHECK (prev_link IS NULL OR octet_length(prev_link) = 32),
+
+    -- Current chain link: Hash(prev_link || job_id || t_hlc || payload_hash)
+    link            BYTEA NOT NULL CHECK (octet_length(link) = 32),
+
+    -- Wall-clock timestamp for operational queries (not authoritative)
     created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
 
-    -- Ensure HLC order is unique within tenant/partition
-    CONSTRAINT uq_scheduler_log_order UNIQUE (tenant_id, partition_key, t_hlc, job_id)
+    -- Ensure unique HLC ordering within tenant/partition
+    CONSTRAINT uq_scheduler_log_order UNIQUE (tenant_id, t_hlc, partition_key, job_id)
 );
 
-COMMENT ON TABLE scheduler.scheduler_log IS
-    'HLC-ordered job log with cryptographic chain linking for audit-safe ordering';
-COMMENT ON COLUMN scheduler.scheduler_log.t_hlc IS
-    'Hybrid Logical Clock timestamp in sortable string format';
-COMMENT ON COLUMN scheduler.scheduler_log.link IS
-    'SHA-256 chain link: Hash(prev_link || job_id || t_hlc || payload_hash)';
-
--- Index for tenant + HLC ordered queries (primary query path)
+-- Primary query: get jobs by HLC order within tenant
 CREATE INDEX IF NOT EXISTS idx_scheduler_log_tenant_hlc
-    ON scheduler.scheduler_log(tenant_id, t_hlc);
+    ON scheduler.scheduler_log (tenant_id, t_hlc ASC);
 
--- Index for partition-scoped queries
+-- Partition-specific queries
 CREATE INDEX IF NOT EXISTS idx_scheduler_log_partition
-    ON scheduler.scheduler_log(tenant_id, partition_key, t_hlc);
+    ON scheduler.scheduler_log (tenant_id, partition_key, t_hlc ASC);
 
--- Index for job_id lookups (idempotency checks)
+-- Job lookup by ID
 CREATE INDEX IF NOT EXISTS idx_scheduler_log_job_id
-    ON scheduler.scheduler_log(job_id);
+    ON scheduler.scheduler_log (job_id);
+
+-- Chain verification: find by link hash
+CREATE INDEX IF NOT EXISTS idx_scheduler_log_link
+    ON scheduler.scheduler_log (link);
+
+-- Range queries for batch snapshots
+CREATE INDEX IF NOT EXISTS idx_scheduler_log_created
+    ON scheduler.scheduler_log (tenant_id, created_at DESC);
+
+COMMENT ON TABLE scheduler.scheduler_log IS 'HLC-ordered scheduler queue with cryptographic chain linking for audit-safe job ordering';
+COMMENT ON COLUMN scheduler.scheduler_log.t_hlc IS 'Hybrid Logical Clock timestamp: authoritative ordering key. Format: physicalTime13-nodeId-counter6';
+COMMENT ON COLUMN scheduler.scheduler_log.link IS 'Chain link = SHA256(prev_link || job_id || t_hlc || payload_hash). Creates tamper-evident sequence.';
 
 -- ============================================================================
--- SECTION 2: Batch Snapshot Table (SQC-003)
+-- SQC-003: scheduler.batch_snapshot - Audit anchors for job batches
 -- ============================================================================
--- Captures chain state at specific points for audit anchors and attestation.
 
 CREATE TABLE IF NOT EXISTS scheduler.batch_snapshot (
-    batch_id        UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    -- Snapshot identifier
+    batch_id        UUID PRIMARY KEY,
+
+    -- Tenant isolation
     tenant_id       TEXT NOT NULL,
-    range_start_t   TEXT NOT NULL,                  -- HLC range start (inclusive)
-    range_end_t     TEXT NOT NULL,                  -- HLC range end (inclusive)
-    head_link       BYTEA NOT NULL,                 -- Chain head at snapshot time
-    job_count       INT NOT NULL,
+
+    -- HLC range covered by this snapshot
+    range_start_t   TEXT NOT NULL,
+    range_end_t     TEXT NOT NULL,
+
+    -- Chain head at snapshot time (last link in range)
+    head_link       BYTEA NOT NULL CHECK (octet_length(head_link) = 32),
+
+    -- Job count for quick validation
+    job_count       INT NOT NULL CHECK (job_count >= 0),
+
+    -- Wall-clock timestamp
     created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-    signed_by       TEXT,                           -- Optional: signing key ID for DSSE
-    signature       BYTEA                           -- Optional: DSSE signature bytes
+
+    -- Optional DSSE signature fields
+    signed_by       TEXT,           -- Key ID that signed
+    signature       BYTEA,          -- DSSE signature bytes
+
+    -- Constraint: signature requires signed_by
+    CONSTRAINT chk_signature_requires_signer CHECK (
+        (signature IS NULL AND signed_by IS NULL) OR
+        (signature IS NOT NULL AND signed_by IS NOT NULL)
+    )
 );
 
-COMMENT ON TABLE scheduler.batch_snapshot IS
-    'Audit anchors capturing chain state at specific HLC ranges';
-COMMENT ON COLUMN scheduler.batch_snapshot.head_link IS
-    'The chain link at range_end_t - can be used to verify chain integrity';
-
--- Index for tenant + time ordered queries
+-- Query snapshots by tenant and time
 CREATE INDEX IF NOT EXISTS idx_batch_snapshot_tenant
-    ON scheduler.batch_snapshot(tenant_id, created_at DESC);
+    ON scheduler.batch_snapshot (tenant_id, created_at DESC);
 
--- Index for HLC range queries
-CREATE INDEX IF NOT EXISTS idx_batch_snapshot_hlc_range
-    ON scheduler.batch_snapshot(tenant_id, range_start_t, range_end_t);
+-- Query snapshots by HLC range
+CREATE INDEX IF NOT EXISTS idx_batch_snapshot_range
+    ON scheduler.batch_snapshot (tenant_id, range_start_t, range_end_t);
+
+COMMENT ON TABLE scheduler.batch_snapshot IS 'Audit anchors for scheduler job batches. Captures chain head at specific HLC ranges.';
+COMMENT ON COLUMN scheduler.batch_snapshot.head_link IS 'Chain head (last link) at snapshot time. Can be verified by replaying chain.';
 
 -- ============================================================================
--- SECTION 3: Chain Heads Table (SQC-004)
+-- SQC-004: scheduler.chain_heads - Per-partition chain head tracking
 -- ============================================================================
--- Tracks the last chain link per tenant/partition for efficient append.
 
 CREATE TABLE IF NOT EXISTS scheduler.chain_heads (
+    -- Tenant isolation
     tenant_id       TEXT NOT NULL,
+
+    -- Partition (empty string for default partition)
     partition_key   TEXT NOT NULL DEFAULT '',
-    last_link       BYTEA NOT NULL,
+
+    -- Last chain link in this partition
+    last_link       BYTEA NOT NULL CHECK (octet_length(last_link) = 32),
+
+    -- Last HLC timestamp in this partition
     last_t_hlc      TEXT NOT NULL,
-    last_job_id     UUID NOT NULL,
+
+    -- Wall-clock timestamp of last update
     updated_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
 
+    -- Primary key: one head per tenant/partition
     PRIMARY KEY (tenant_id, partition_key)
 );
 
-COMMENT ON TABLE scheduler.chain_heads IS
-    'Per-partition chain head tracking for efficient chain append operations';
+-- Query chain heads by update time (for monitoring)
+CREATE INDEX IF NOT EXISTS idx_chain_heads_updated
+    ON scheduler.chain_heads (updated_at DESC);
 
--- Trigger to update updated_at on chain_heads modifications
-CREATE OR REPLACE TRIGGER update_chain_heads_updated_at
-    BEFORE UPDATE ON scheduler.chain_heads
-    FOR EACH ROW
-    EXECUTE FUNCTION scheduler.update_updated_at();
+COMMENT ON TABLE scheduler.chain_heads IS 'Tracks current chain head for each tenant/partition. Updated atomically with scheduler_log inserts.';
+COMMENT ON COLUMN scheduler.chain_heads.last_link IS 'Current chain head. Used as prev_link for next enqueue.';
 
 -- ============================================================================
--- SECTION 4: Helper Functions
+-- Atomic upsert function for chain head updates
 -- ============================================================================
 
--- Function to get the current chain head for a tenant/partition
-CREATE OR REPLACE FUNCTION scheduler.get_chain_head(
-    p_tenant_id TEXT,
-    p_partition_key TEXT DEFAULT ''
-)
-RETURNS TABLE (
-    last_link BYTEA,
-    last_t_hlc TEXT,
-    last_job_id UUID
-)
-LANGUAGE plpgsql STABLE
-AS $$
-BEGIN
-    RETURN QUERY
-    SELECT ch.last_link, ch.last_t_hlc, ch.last_job_id
-    FROM scheduler.chain_heads ch
-    WHERE ch.tenant_id = p_tenant_id
-      AND ch.partition_key = p_partition_key;
-END;
-$$;
-
--- Function to insert log entry and update chain head atomically
-CREATE OR REPLACE FUNCTION scheduler.insert_log_with_chain_update(
-    p_tenant_id TEXT,
-    p_t_hlc TEXT,
+CREATE OR REPLACE FUNCTION scheduler.upsert_chain_head(
+    p_tenant_id     TEXT,
     p_partition_key TEXT,
-    p_job_id UUID,
-    p_payload_hash BYTEA,
-    p_prev_link BYTEA,
-    p_link BYTEA
+    p_new_link      BYTEA,
+    p_new_t_hlc     TEXT
 )
-RETURNS BIGINT
+RETURNS VOID
 LANGUAGE plpgsql
 AS $$
-DECLARE
-    v_seq BIGINT;
 BEGIN
-    -- Insert log entry
-    INSERT INTO scheduler.scheduler_log (
-        tenant_id, t_hlc, partition_key, job_id,
-        payload_hash, prev_link, link
-    )
-    VALUES (
-        p_tenant_id, p_t_hlc, p_partition_key, p_job_id,
-        p_payload_hash, p_prev_link, p_link
-    )
-    RETURNING seq_bigint INTO v_seq;
-
-    -- Upsert chain head
-    INSERT INTO scheduler.chain_heads (
-        tenant_id, partition_key, last_link, last_t_hlc, last_job_id
-    )
-    VALUES (
-        p_tenant_id, p_partition_key, p_link, p_t_hlc, p_job_id
-    )
+    INSERT INTO scheduler.chain_heads (tenant_id, partition_key, last_link, last_t_hlc, updated_at)
+    VALUES (p_tenant_id, p_partition_key, p_new_link, p_new_t_hlc, NOW())
     ON CONFLICT (tenant_id, partition_key)
     DO UPDATE SET
         last_link = EXCLUDED.last_link,
         last_t_hlc = EXCLUDED.last_t_hlc,
-        last_job_id = EXCLUDED.last_job_id,
-        updated_at = NOW();
-
-    RETURN v_seq;
+        updated_at = EXCLUDED.updated_at
+    WHERE scheduler.chain_heads.last_t_hlc < EXCLUDED.last_t_hlc;
 END;
 $$;
 
-COMMENT ON FUNCTION scheduler.insert_log_with_chain_update IS
-    'Atomically inserts a scheduler log entry and updates the chain head';
-
-COMMIT;
+COMMENT ON FUNCTION scheduler.upsert_chain_head IS 'Atomically updates chain head. Only updates if new HLC > current HLC (monotonicity).';

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Postgres/Models/BatchSnapshotEntity.cs

@@ -0,0 +1,58 @@
+// -----------------------------------------------------------------------------
+// BatchSnapshotEntity.cs
+// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
+// Task: SQC-005 - Entity for batch_snapshot table
+// -----------------------------------------------------------------------------
+
+namespace StellaOps.Scheduler.Persistence.Postgres.Models;
+
+/// <summary>
+/// Entity representing an audit anchor for a batch of scheduler jobs.
+/// </summary>
+public sealed record BatchSnapshotEntity
+{
+    /// <summary>
+    /// Snapshot identifier.
+    /// </summary>
+    public required Guid BatchId { get; init; }
+
+    /// <summary>
+    /// Tenant identifier for isolation.
+    /// </summary>
+    public required string TenantId { get; init; }
+
+    /// <summary>
+    /// HLC range start (inclusive).
+    /// </summary>
+    public required string RangeStartT { get; init; }
+
+    /// <summary>
+    /// HLC range end (inclusive).
+    /// </summary>
+    public required string RangeEndT { get; init; }
+
+    /// <summary>
+    /// Chain head at snapshot time (last link in range).
+    /// </summary>
+    public required byte[] HeadLink { get; init; }
+
+    /// <summary>
+    /// Number of jobs in the snapshot range.
+    /// </summary>
+    public required int JobCount { get; init; }
+
+    /// <summary>
+    /// Wall-clock timestamp of snapshot creation.
+    /// </summary>
+    public required DateTimeOffset CreatedAt { get; init; }
+
+    /// <summary>
+    /// Key ID that signed the snapshot (null if unsigned).
+    /// </summary>
+    public string? SignedBy { get; init; }
+
+    /// <summary>
+    /// DSSE signature bytes (null if unsigned).
+    /// </summary>
+    public byte[]? Signature { get; init; }
+}

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Postgres/Models/ChainHeadEntity.cs

@@ -0,0 +1,38 @@
+// -----------------------------------------------------------------------------
+// ChainHeadEntity.cs
+// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
+// Task: SQC-005 - Entity for chain_heads table
+// -----------------------------------------------------------------------------
+
+namespace StellaOps.Scheduler.Persistence.Postgres.Models;
+
+/// <summary>
+/// Entity representing the current chain head for a tenant/partition.
+/// </summary>
+public sealed record ChainHeadEntity
+{
+    /// <summary>
+    /// Tenant identifier for isolation.
+    /// </summary>
+    public required string TenantId { get; init; }
+
+    /// <summary>
+    /// Partition key (empty string for default partition).
+    /// </summary>
+    public string PartitionKey { get; init; } = "";
+
+    /// <summary>
+    /// Last chain link in this partition.
+    /// </summary>
+    public required byte[] LastLink { get; init; }
+
+    /// <summary>
+    /// Last HLC timestamp in this partition.
+    /// </summary>
+    public required string LastTHlc { get; init; }
+
+    /// <summary>
+    /// Wall-clock timestamp of last update.
+    /// </summary>
+    public required DateTimeOffset UpdatedAt { get; init; }
+}

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Postgres/Models/SchedulerLogEntity.cs

@@ -0,0 +1,60 @@
+// -----------------------------------------------------------------------------
+// SchedulerLogEntity.cs
+// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
+// Task: SQC-005 - Entity for scheduler_log table
+// -----------------------------------------------------------------------------
+
+namespace StellaOps.Scheduler.Persistence.Postgres.Models;
+
+/// <summary>
+/// Entity representing an HLC-ordered, chain-linked scheduler log entry.
+/// </summary>
+public sealed record SchedulerLogEntity
+{
+    /// <summary>
+    /// Storage sequence number (BIGSERIAL, not authoritative for ordering).
+    /// Populated by the database on insert; 0 for new entries before persistence.
+    /// </summary>
+    public long SeqBigint { get; init; }
+
+    /// <summary>
+    /// Tenant identifier for isolation.
+    /// </summary>
+    public required string TenantId { get; init; }
+
+    /// <summary>
+    /// HLC timestamp string: "1704067200000-scheduler-east-1-000042".
+    /// This is the authoritative ordering key.
+    /// </summary>
+    public required string THlc { get; init; }
+
+    /// <summary>
+    /// Optional queue partition for parallel processing.
+    /// </summary>
+    public string PartitionKey { get; init; } = "";
+
+    /// <summary>
+    /// Job identifier (deterministic from payload using GUID v5).
+    /// </summary>
+    public required Guid JobId { get; init; }
+
+    /// <summary>
+    /// SHA-256 of canonical JSON payload (32 bytes).
+    /// </summary>
+    public required byte[] PayloadHash { get; init; }
+
+    /// <summary>
+    /// Previous chain link (null for first entry in partition).
+    /// </summary>
+    public byte[]? PrevLink { get; init; }
+
+    /// <summary>
+    /// Current chain link: Hash(prev_link || job_id || t_hlc || payload_hash).
+    /// </summary>
+    public required byte[] Link { get; init; }
+
+    /// <summary>
+    /// Wall-clock timestamp for operational queries (not authoritative).
+    /// </summary>
+    public required DateTimeOffset CreatedAt { get; init; }
+}

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Postgres/Repositories/BatchSnapshotRepository.cs

@@ -0,0 +1,179 @@
+// -----------------------------------------------------------------------------
+// BatchSnapshotRepository.cs
+// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
+// Task: SQC-013 - Implement BatchSnapshotService
+// -----------------------------------------------------------------------------
+
+using Microsoft.Extensions.Logging;
+using Npgsql;
+using StellaOps.Infrastructure.Postgres.Repositories;
+using StellaOps.Scheduler.Persistence.Postgres.Models;
+
+namespace StellaOps.Scheduler.Persistence.Postgres.Repositories;
+
+/// <summary>
+/// PostgreSQL implementation of batch snapshot repository.
+/// </summary>
+public sealed class BatchSnapshotRepository : RepositoryBase<SchedulerDataSource>, IBatchSnapshotRepository
+{
+    public BatchSnapshotRepository(
+        SchedulerDataSource dataSource,
+        ILogger<BatchSnapshotRepository> logger)
+        : base(dataSource, logger)
+    {
+    }
+
+    /// <inheritdoc />
+    public async Task InsertAsync(BatchSnapshotEntity snapshot, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(snapshot);
+
+        const string sql = """
+            INSERT INTO scheduler.batch_snapshot (
+                batch_id, tenant_id, range_start_t, range_end_t,
+                head_link, job_count, created_at, signed_by, signature
+            ) VALUES (
+                @batch_id, @tenant_id, @range_start_t, @range_end_t,
+                @head_link, @job_count, @created_at, @signed_by, @signature
+            )
+            """;
+
+        await using var connection = await DataSource.OpenConnectionAsync(snapshot.TenantId, "writer", cancellationToken)
+            .ConfigureAwait(false);
+        await using var command = CreateCommand(sql, connection);
+
+        AddParameter(command, "batch_id", snapshot.BatchId);
+        AddParameter(command, "tenant_id", snapshot.TenantId);
+        AddParameter(command, "range_start_t", snapshot.RangeStartT);
+        AddParameter(command, "range_end_t", snapshot.RangeEndT);
+        AddParameter(command, "head_link", snapshot.HeadLink);
+        AddParameter(command, "job_count", snapshot.JobCount);
+        AddParameter(command, "created_at", snapshot.CreatedAt);
+        AddParameter(command, "signed_by", snapshot.SignedBy);
+        AddParameter(command, "signature", snapshot.Signature);
+
+        await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<BatchSnapshotEntity?> GetByIdAsync(Guid batchId, CancellationToken cancellationToken = default)
+    {
+        const string sql = """
+            SELECT batch_id, tenant_id, range_start_t, range_end_t,
+                   head_link, job_count, created_at, signed_by, signature
+            FROM scheduler.batch_snapshot
+            WHERE batch_id = @batch_id
+            """;
+
+        return await QuerySingleOrDefaultAsync(
+            tenantId: null!,
+            sql,
+            cmd => AddParameter(cmd, "batch_id", batchId),
+            MapBatchSnapshot,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<BatchSnapshotEntity>> GetByTenantAsync(
+        string tenantId,
+        int limit = 100,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(tenantId);
+
+        const string sql = """
+            SELECT batch_id, tenant_id, range_start_t, range_end_t,
+                   head_link, job_count, created_at, signed_by, signature
+            FROM scheduler.batch_snapshot
+            WHERE tenant_id = @tenant_id
+            ORDER BY created_at DESC
+            LIMIT @limit
+            """;
+
+        return await QueryAsync(
+            tenantId,
+            sql,
+            cmd =>
+            {
+                AddParameter(cmd, "tenant_id", tenantId);
+                AddParameter(cmd, "limit", limit);
+            },
+            MapBatchSnapshot,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<BatchSnapshotEntity>> GetContainingHlcAsync(
+        string tenantId,
+        string tHlc,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(tenantId);
+        ArgumentException.ThrowIfNullOrWhiteSpace(tHlc);
+
+        const string sql = """
+            SELECT batch_id, tenant_id, range_start_t, range_end_t,
+                   head_link, job_count, created_at, signed_by, signature
+            FROM scheduler.batch_snapshot
+            WHERE tenant_id = @tenant_id
+              AND range_start_t <= @t_hlc
+              AND range_end_t >= @t_hlc
+            ORDER BY created_at DESC
+            """;
+
+        return await QueryAsync(
+            tenantId,
+            sql,
+            cmd =>
+            {
+                AddParameter(cmd, "tenant_id", tenantId);
+                AddParameter(cmd, "t_hlc", tHlc);
+            },
+            MapBatchSnapshot,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<BatchSnapshotEntity?> GetLatestAsync(
+        string tenantId,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(tenantId);
+
+        const string sql = """
+            SELECT batch_id, tenant_id, range_start_t, range_end_t,
+                   head_link, job_count, created_at, signed_by, signature
+            FROM scheduler.batch_snapshot
+            WHERE tenant_id = @tenant_id
+            ORDER BY created_at DESC
+            LIMIT 1
+            """;
+
+        return await QuerySingleOrDefaultAsync(
+            tenantId,
+            sql,
+            cmd => AddParameter(cmd, "tenant_id", tenantId),
+            MapBatchSnapshot,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    private static BatchSnapshotEntity MapBatchSnapshot(NpgsqlDataReader reader)
+    {
+        return new BatchSnapshotEntity
+        {
+            BatchId = reader.GetGuid(reader.GetOrdinal("batch_id")),
+            TenantId = reader.GetString(reader.GetOrdinal("tenant_id")),
+            RangeStartT = reader.GetString(reader.GetOrdinal("range_start_t")),
+            RangeEndT = reader.GetString(reader.GetOrdinal("range_end_t")),
+            HeadLink = reader.GetFieldValue<byte[]>(reader.GetOrdinal("head_link")),
+            JobCount = reader.GetInt32(reader.GetOrdinal("job_count")),
+            CreatedAt = reader.GetFieldValue<DateTimeOffset>(reader.GetOrdinal("created_at")),
+            SignedBy = reader.IsDBNull(reader.GetOrdinal("signed_by"))
+                ? null
+                : reader.GetString(reader.GetOrdinal("signed_by")),
+            Signature = reader.IsDBNull(reader.GetOrdinal("signature"))
+                ? null
+                : reader.GetFieldValue<byte[]>(reader.GetOrdinal("signature"))
+        };
+    }
+}

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Postgres/Repositories/ChainHeadRepository.cs

@@ -0,0 +1,140 @@
+// -----------------------------------------------------------------------------
+// ChainHeadRepository.cs
+// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
+// Task: SQC-007 - PostgreSQL implementation for chain_heads repository
+// -----------------------------------------------------------------------------
+
+using Microsoft.Extensions.Logging;
+using Npgsql;
+using StellaOps.Infrastructure.Postgres.Repositories;
+using StellaOps.Scheduler.Persistence.Postgres.Models;
+
+namespace StellaOps.Scheduler.Persistence.Postgres.Repositories;
+
+/// <summary>
+/// PostgreSQL repository for chain head tracking operations.
+/// </summary>
+public sealed class ChainHeadRepository : RepositoryBase<SchedulerDataSource>, IChainHeadRepository
+{
+    /// <summary>
+    /// Creates a new chain head repository.
+    /// </summary>
+    public ChainHeadRepository(
+        SchedulerDataSource dataSource,
+        ILogger<ChainHeadRepository> logger)
+        : base(dataSource, logger)
+    {
+    }
+
+    /// <inheritdoc />
+    public async Task<ChainHeadEntity?> GetAsync(
+        string tenantId,
+        string partitionKey,
+        CancellationToken cancellationToken = default)
+    {
+        const string sql = """
+            SELECT tenant_id, partition_key, last_link, last_t_hlc, updated_at
+            FROM scheduler.chain_heads
+            WHERE tenant_id = @tenant_id AND partition_key = @partition_key
+            """;
+
+        return await QuerySingleOrDefaultAsync(
+            tenantId,
+            sql,
+            cmd =>
+            {
+                AddParameter(cmd, "tenant_id", tenantId);
+                AddParameter(cmd, "partition_key", partitionKey);
+            },
+            MapChainHeadEntity,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<byte[]?> GetLastLinkAsync(
+        string tenantId,
+        string partitionKey,
+        CancellationToken cancellationToken = default)
+    {
+        const string sql = """
+            SELECT last_link
+            FROM scheduler.chain_heads
+            WHERE tenant_id = @tenant_id AND partition_key = @partition_key
+            """;
+
+        await using var connection = await DataSource.OpenConnectionAsync(tenantId, "reader", cancellationToken)
+            .ConfigureAwait(false);
+        await using var command = CreateCommand(sql, connection);
+
+        AddParameter(command, "tenant_id", tenantId);
+        AddParameter(command, "partition_key", partitionKey);
+
+        var result = await command.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false);
+        return result is DBNull or null ? null : (byte[])result;
+    }
+
+    /// <inheritdoc />
+    public async Task<bool> UpsertAsync(
+        string tenantId,
+        string partitionKey,
+        byte[] newLink,
+        string newTHlc,
+        CancellationToken cancellationToken = default)
+    {
+        // Use the upsert function with monotonicity check
+        const string sql = """
+            INSERT INTO scheduler.chain_heads (tenant_id, partition_key, last_link, last_t_hlc, updated_at)
+            VALUES (@tenant_id, @partition_key, @new_link, @new_t_hlc, NOW())
+            ON CONFLICT (tenant_id, partition_key)
+            DO UPDATE SET
+                last_link = EXCLUDED.last_link,
+                last_t_hlc = EXCLUDED.last_t_hlc,
+                updated_at = EXCLUDED.updated_at
+            WHERE scheduler.chain_heads.last_t_hlc < EXCLUDED.last_t_hlc
+            """;
+
+        await using var connection = await DataSource.OpenConnectionAsync(tenantId, "writer", cancellationToken)
+            .ConfigureAwait(false);
+        await using var command = CreateCommand(sql, connection);
+
+        AddParameter(command, "tenant_id", tenantId);
+        AddParameter(command, "partition_key", partitionKey);
+        AddParameter(command, "new_link", newLink);
+        AddParameter(command, "new_t_hlc", newTHlc);
+
+        var rowsAffected = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+        return rowsAffected > 0;
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<ChainHeadEntity>> GetAllForTenantAsync(
+        string tenantId,
+        CancellationToken cancellationToken = default)
+    {
+        const string sql = """
+            SELECT tenant_id, partition_key, last_link, last_t_hlc, updated_at
+            FROM scheduler.chain_heads
+            WHERE tenant_id = @tenant_id
+            ORDER BY partition_key
+            """;
+
+        return await QueryAsync(
+            tenantId,
+            sql,
+            cmd => AddParameter(cmd, "tenant_id", tenantId),
+            MapChainHeadEntity,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    private static ChainHeadEntity MapChainHeadEntity(NpgsqlDataReader reader)
+    {
+        return new ChainHeadEntity
+        {
+            TenantId = reader.GetString(reader.GetOrdinal("tenant_id")),
+            PartitionKey = reader.GetString(reader.GetOrdinal("partition_key")),
+            LastLink = reader.GetFieldValue<byte[]>(reader.GetOrdinal("last_link")),
+            LastTHlc = reader.GetString(reader.GetOrdinal("last_t_hlc")),
+            UpdatedAt = reader.GetFieldValue<DateTimeOffset>(reader.GetOrdinal("updated_at"))
+        };
+    }
+}

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Postgres/Repositories/IBatchSnapshotRepository.cs

@@ -1,6 +1,8 @@
-// <copyright file="IBatchSnapshotRepository.cs" company="StellaOps">
-// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
-// </copyright>
+// -----------------------------------------------------------------------------
+// IBatchSnapshotRepository.cs
+// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
+// Task: SQC-013 - Implement BatchSnapshotService
+// -----------------------------------------------------------------------------
 
 using StellaOps.Scheduler.Persistence.Postgres.Models;
 
@@ -16,50 +18,33 @@ public interface IBatchSnapshotRepository
     /// </summary>
     /// <param name="snapshot">The snapshot to insert.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A task representing the operation.</returns>
-    Task InsertAsync(BatchSnapshot snapshot, CancellationToken cancellationToken = default);
+    Task InsertAsync(BatchSnapshotEntity snapshot, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Gets a batch snapshot by ID.
     /// </summary>
-    /// <param name="batchId">The batch identifier.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>The snapshot if found.</returns>
-    Task<BatchSnapshot?> GetByIdAsync(Guid batchId, CancellationToken cancellationToken = default);
+    Task<BatchSnapshotEntity?> GetByIdAsync(Guid batchId, CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Gets the most recent batch snapshot for a tenant.
+    /// Gets batch snapshots for a tenant, ordered by creation time descending.
     /// </summary>
-    /// <param name="tenantId">Tenant identifier.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>The most recent snapshot if found.</returns>
-    Task<BatchSnapshot?> GetLatestAsync(string tenantId, CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Gets batch snapshots for a tenant within a time range.
-    /// </summary>
-    /// <param name="tenantId">Tenant identifier.</param>
-    /// <param name="startTime">Start time (inclusive).</param>
-    /// <param name="endTime">End time (inclusive).</param>
-    /// <param name="limit">Maximum snapshots to return.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>Snapshots in the specified range.</returns>
-    Task<IReadOnlyList<BatchSnapshot>> GetByTimeRangeAsync(
+    Task<IReadOnlyList<BatchSnapshotEntity>> GetByTenantAsync(
         string tenantId,
-        DateTimeOffset startTime,
-        DateTimeOffset endTime,
         int limit = 100,
         CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Gets batch snapshots containing a specific HLC timestamp.
+    /// Gets batch snapshots that contain a specific HLC timestamp.
     /// </summary>
-    /// <param name="tenantId">Tenant identifier.</param>
-    /// <param name="tHlc">The HLC timestamp to search for.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>Snapshots containing the timestamp.</returns>
-    Task<IReadOnlyList<BatchSnapshot>> GetContainingHlcAsync(
+    Task<IReadOnlyList<BatchSnapshotEntity>> GetContainingHlcAsync(
         string tenantId,
         string tHlc,
         CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets the latest batch snapshot for a tenant.
+    /// </summary>
+    Task<BatchSnapshotEntity?> GetLatestAsync(
+        string tenantId,
+        CancellationToken cancellationToken = default);
 }

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Postgres/Repositories/IChainHeadRepository.cs

@@ -1,47 +1,64 @@
-// <copyright file="IChainHeadRepository.cs" company="StellaOps">
-// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
-// </copyright>
+// -----------------------------------------------------------------------------
+// IChainHeadRepository.cs
+// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
+// Task: SQC-007 - Interface for chain_heads repository
+// -----------------------------------------------------------------------------
 
 using StellaOps.Scheduler.Persistence.Postgres.Models;
 
 namespace StellaOps.Scheduler.Persistence.Postgres.Repositories;
 
 /// <summary>
-/// Repository interface for chain head operations.
+/// Repository interface for chain head tracking operations.
 /// </summary>
 public interface IChainHeadRepository
 {
     /// <summary>
-    /// Gets the last chain link for a tenant/partition.
+    /// Gets the current chain head for a tenant/partition.
     /// </summary>
     /// <param name="tenantId">Tenant identifier.</param>
     /// <param name="partitionKey">Partition key (empty string for default).</param>
     /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>The last link bytes, or null if no chain exists.</returns>
+    /// <returns>Current chain head, or null if no entries exist.</returns>
+    Task<ChainHeadEntity?> GetAsync(
+        string tenantId,
+        string partitionKey,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Gets the last link hash for a tenant/partition.
+    /// Convenience method for chain linking operations.
+    /// </summary>
+    /// <param name="tenantId">Tenant identifier.</param>
+    /// <param name="partitionKey">Partition key (empty string for default).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>Last link hash, or null if no entries exist.</returns>
     Task<byte[]?> GetLastLinkAsync(
         string tenantId,
         string partitionKey,
         CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Gets the full chain head for a tenant/partition.
+    /// Updates the chain head atomically with monotonicity check.
+    /// Only updates if new HLC > current HLC.
     /// </summary>
     /// <param name="tenantId">Tenant identifier.</param>
     /// <param name="partitionKey">Partition key (empty string for default).</param>
+    /// <param name="newLink">New chain link.</param>
+    /// <param name="newTHlc">New HLC timestamp.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>The chain head, or null if no chain exists.</returns>
-    Task<ChainHead?> GetAsync(
+    /// <returns>True if updated, false if skipped due to monotonicity.</returns>
+    Task<bool> UpsertAsync(
         string tenantId,
         string partitionKey,
+        byte[] newLink,
+        string newTHlc,
         CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Gets all chain heads for a tenant.
     /// </summary>
-    /// <param name="tenantId">Tenant identifier.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>All chain heads for the tenant.</returns>
-    Task<IReadOnlyList<ChainHead>> GetAllForTenantAsync(
+    Task<IReadOnlyList<ChainHeadEntity>> GetAllForTenantAsync(
         string tenantId,
         CancellationToken cancellationToken = default);
 }

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Postgres/Repositories/ISchedulerLogRepository.cs

@@ -1,6 +1,8 @@
-// <copyright file="ISchedulerLogRepository.cs" company="StellaOps">
-// Copyright (c) StellaOps. Licensed under AGPL-3.0-or-later.
-// </copyright>
+// -----------------------------------------------------------------------------
+// ISchedulerLogRepository.cs
+// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
+// Task: SQC-005 - Interface for scheduler_log repository
+// -----------------------------------------------------------------------------
 
 using StellaOps.Scheduler.Persistence.Postgres.Models;
 
@@ -12,98 +14,61 @@ namespace StellaOps.Scheduler.Persistence.Postgres.Repositories;
 public interface ISchedulerLogRepository
 {
     /// <summary>
-    /// Inserts a log entry and atomically updates the chain head.
+    /// Inserts a new log entry and atomically updates the chain head.
     /// </summary>
     /// <param name="entry">The log entry to insert.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>The sequence number of the inserted entry.</returns>
-    Task<long> InsertWithChainUpdateAsync(
-        SchedulerLogEntry entry,
+    /// <returns>The inserted entry with populated seq_bigint.</returns>
+    Task<SchedulerLogEntity> InsertWithChainUpdateAsync(
+        SchedulerLogEntity entry,
         CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Gets log entries ordered by HLC timestamp.
+    /// Gets log entries by HLC order within a tenant/partition.
     /// </summary>
     /// <param name="tenantId">Tenant identifier.</param>
     /// <param name="partitionKey">Optional partition key (null for all partitions).</param>
     /// <param name="limit">Maximum entries to return.</param>
     /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>Log entries in HLC order.</returns>
-    Task<IReadOnlyList<SchedulerLogEntry>> GetByHlcOrderAsync(
+    Task<IReadOnlyList<SchedulerLogEntity>> GetByHlcOrderAsync(
         string tenantId,
         string? partitionKey,
         int limit,
         CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Gets log entries within an HLC timestamp range.
+    /// Gets log entries within an HLC range.
     /// </summary>
     /// <param name="tenantId">Tenant identifier.</param>
-    /// <param name="startTHlc">Start timestamp (inclusive, null for unbounded).</param>
-    /// <param name="endTHlc">End timestamp (inclusive, null for unbounded).</param>
-    /// <param name="limit">Maximum entries to return (0 for unlimited).</param>
-    /// <param name="partitionKey">Optional partition key (null for all partitions).</param>
+    /// <param name="startTHlc">Start HLC (inclusive, null for no lower bound).</param>
+    /// <param name="endTHlc">End HLC (inclusive, null for no upper bound).</param>
     /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>Log entries in the specified range.</returns>
-    Task<IReadOnlyList<SchedulerLogEntry>> GetByHlcRangeAsync(
+    Task<IReadOnlyList<SchedulerLogEntity>> GetByHlcRangeAsync(
         string tenantId,
         string? startTHlc,
         string? endTHlc,
-        int limit = 0,
-        string? partitionKey = null,
-        CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Gets log entries after an HLC timestamp (cursor-based pagination).
-    /// </summary>
-    /// <param name="tenantId">Tenant identifier.</param>
-    /// <param name="afterTHlc">Start after this timestamp (exclusive).</param>
-    /// <param name="limit">Maximum entries to return.</param>
-    /// <param name="partitionKey">Optional partition key (null for all partitions).</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>Log entries after the specified timestamp.</returns>
-    Task<IReadOnlyList<SchedulerLogEntry>> GetAfterHlcAsync(
-        string tenantId,
-        string afterTHlc,
-        int limit,
-        string? partitionKey = null,
-        CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Counts log entries within an HLC timestamp range.
-    /// </summary>
-    /// <param name="tenantId">Tenant identifier.</param>
-    /// <param name="startTHlc">Start timestamp (inclusive, null for unbounded).</param>
-    /// <param name="endTHlc">End timestamp (inclusive, null for unbounded).</param>
-    /// <param name="partitionKey">Optional partition key (null for all partitions).</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>Count of entries in the range.</returns>
-    Task<int> CountByHlcRangeAsync(
-        string tenantId,
-        string? startTHlc,
-        string? endTHlc,
-        string? partitionKey = null,
         CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Gets a log entry by job ID.
     /// </summary>
-    /// <param name="jobId">Job identifier.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>The log entry if found.</returns>
-    Task<SchedulerLogEntry?> GetByJobIdAsync(
+    Task<SchedulerLogEntity?> GetByJobIdAsync(
         Guid jobId,
         CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Checks if a job ID already exists in the log.
+    /// Gets a log entry by its chain link hash.
     /// </summary>
-    /// <param name="tenantId">Tenant identifier.</param>
-    /// <param name="jobId">Job identifier.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>True if the job exists.</returns>
-    Task<bool> ExistsAsync(
+    Task<SchedulerLogEntity?> GetByLinkAsync(
+        byte[] link,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Counts entries in an HLC range.
+    /// </summary>
+    Task<int> CountByHlcRangeAsync(
         string tenantId,
-        Guid jobId,
+        string? startTHlc,
+        string? endTHlc,
         CancellationToken cancellationToken = default);
 }

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Postgres/Repositories/SchedulerLogRepository.cs

@@ -0,0 +1,270 @@
+// -----------------------------------------------------------------------------
+// SchedulerLogRepository.cs
+// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
+// Task: SQC-006 - PostgreSQL implementation for scheduler_log repository
+// -----------------------------------------------------------------------------
+
+using Microsoft.Extensions.Logging;
+using Npgsql;
+using StellaOps.Infrastructure.Postgres.Repositories;
+using StellaOps.Scheduler.Persistence.Postgres.Models;
+
+namespace StellaOps.Scheduler.Persistence.Postgres.Repositories;
+
+/// <summary>
+/// PostgreSQL repository for HLC-ordered scheduler log operations.
+/// </summary>
+public sealed class SchedulerLogRepository : RepositoryBase<SchedulerDataSource>, ISchedulerLogRepository
+{
+    private readonly IChainHeadRepository _chainHeadRepository;
+
+    /// <summary>
+    /// Creates a new scheduler log repository.
+    /// </summary>
+    public SchedulerLogRepository(
+        SchedulerDataSource dataSource,
+        ILogger<SchedulerLogRepository> logger,
+        IChainHeadRepository chainHeadRepository)
+        : base(dataSource, logger)
+    {
+        _chainHeadRepository = chainHeadRepository;
+    }
+
+    /// <inheritdoc />
+    public async Task<SchedulerLogEntity> InsertWithChainUpdateAsync(
+        SchedulerLogEntity entry,
+        CancellationToken cancellationToken = default)
+    {
+        const string sql = """
+            INSERT INTO scheduler.scheduler_log (
+                tenant_id, t_hlc, partition_key, job_id, payload_hash, prev_link, link
+            )
+            VALUES (
+                @tenant_id, @t_hlc, @partition_key, @job_id, @payload_hash, @prev_link, @link
+            )
+            RETURNING seq_bigint, tenant_id, t_hlc, partition_key, job_id, payload_hash, prev_link, link, created_at
+            """;
+
+        await using var connection = await DataSource.OpenConnectionAsync(entry.TenantId, "writer", cancellationToken)
+            .ConfigureAwait(false);
+
+        // Use transaction for atomicity of log insert + chain head update
+        await using var transaction = await connection.BeginTransactionAsync(cancellationToken).ConfigureAwait(false);
+
+        try
+        {
+            await using var command = CreateCommand(sql, connection);
+            command.Transaction = transaction;
+
+            AddParameter(command, "tenant_id", entry.TenantId);
+            AddParameter(command, "t_hlc", entry.THlc);
+            AddParameter(command, "partition_key", entry.PartitionKey);
+            AddParameter(command, "job_id", entry.JobId);
+            AddParameter(command, "payload_hash", entry.PayloadHash);
+            AddParameter(command, "prev_link", entry.PrevLink);
+            AddParameter(command, "link", entry.Link);
+
+            await using var reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false);
+            await reader.ReadAsync(cancellationToken).ConfigureAwait(false);
+            var result = MapSchedulerLogEntry(reader);
+            await reader.CloseAsync().ConfigureAwait(false);
+
+            // Update chain head atomically
+            await _chainHeadRepository.UpsertAsync(
+                entry.TenantId,
+                entry.PartitionKey,
+                entry.Link,
+                entry.THlc,
+                cancellationToken).ConfigureAwait(false);
+
+            await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
+
+            return result;
+        }
+        catch
+        {
+            await transaction.RollbackAsync(cancellationToken).ConfigureAwait(false);
+            throw;
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<SchedulerLogEntity>> GetByHlcOrderAsync(
+        string tenantId,
+        string? partitionKey,
+        int limit,
+        CancellationToken cancellationToken = default)
+    {
+        var sql = partitionKey is not null
+            ? """
+              SELECT seq_bigint, tenant_id, t_hlc, partition_key, job_id, payload_hash, prev_link, link, created_at
+              FROM scheduler.scheduler_log
+              WHERE tenant_id = @tenant_id AND partition_key = @partition_key
+              ORDER BY t_hlc ASC
+              LIMIT @limit
+              """
+            : """
+              SELECT seq_bigint, tenant_id, t_hlc, partition_key, job_id, payload_hash, prev_link, link, created_at
+              FROM scheduler.scheduler_log
+              WHERE tenant_id = @tenant_id
+              ORDER BY t_hlc ASC
+              LIMIT @limit
+              """;
+
+        return await QueryAsync(
+            tenantId,
+            sql,
+            cmd =>
+            {
+                AddParameter(cmd, "tenant_id", tenantId);
+                if (partitionKey is not null)
+                {
+                    AddParameter(cmd, "partition_key", partitionKey);
+                }
+                AddParameter(cmd, "limit", limit);
+            },
+            MapSchedulerLogEntry,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<SchedulerLogEntity>> GetByHlcRangeAsync(
+        string tenantId,
+        string? startTHlc,
+        string? endTHlc,
+        CancellationToken cancellationToken = default)
+    {
+        var whereClause = "WHERE tenant_id = @tenant_id";
+        if (startTHlc is not null)
+        {
+            whereClause += " AND t_hlc >= @start_t_hlc";
+        }
+        if (endTHlc is not null)
+        {
+            whereClause += " AND t_hlc <= @end_t_hlc";
+        }
+
+        var sql = $"""
+            SELECT seq_bigint, tenant_id, t_hlc, partition_key, job_id, payload_hash, prev_link, link, created_at
+            FROM scheduler.scheduler_log
+            {whereClause}
+            ORDER BY t_hlc ASC
+            """;
+
+        return await QueryAsync(
+            tenantId,
+            sql,
+            cmd =>
+            {
+                AddParameter(cmd, "tenant_id", tenantId);
+                if (startTHlc is not null)
+                {
+                    AddParameter(cmd, "start_t_hlc", startTHlc);
+                }
+                if (endTHlc is not null)
+                {
+                    AddParameter(cmd, "end_t_hlc", endTHlc);
+                }
+            },
+            MapSchedulerLogEntry,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<SchedulerLogEntity?> GetByJobIdAsync(
+        Guid jobId,
+        CancellationToken cancellationToken = default)
+    {
+        const string sql = """
+            SELECT seq_bigint, tenant_id, t_hlc, partition_key, job_id, payload_hash, prev_link, link, created_at
+            FROM scheduler.scheduler_log
+            WHERE job_id = @job_id
+            """;
+
+        // Job ID lookup doesn't require tenant context
+        return await QuerySingleOrDefaultAsync(
+            tenantId: null!,
+            sql,
+            cmd => AddParameter(cmd, "job_id", jobId),
+            MapSchedulerLogEntry,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<SchedulerLogEntity?> GetByLinkAsync(
+        byte[] link,
+        CancellationToken cancellationToken = default)
+    {
+        const string sql = """
+            SELECT seq_bigint, tenant_id, t_hlc, partition_key, job_id, payload_hash, prev_link, link, created_at
+            FROM scheduler.scheduler_log
+            WHERE link = @link
+            """;
+
+        return await QuerySingleOrDefaultAsync(
+            tenantId: null!,
+            sql,
+            cmd => AddParameter(cmd, "link", link),
+            MapSchedulerLogEntry,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<int> CountByHlcRangeAsync(
+        string tenantId,
+        string? startTHlc,
+        string? endTHlc,
+        CancellationToken cancellationToken = default)
+    {
+        var whereClause = "WHERE tenant_id = @tenant_id";
+        if (startTHlc is not null)
+        {
+            whereClause += " AND t_hlc >= @start_t_hlc";
+        }
+        if (endTHlc is not null)
+        {
+            whereClause += " AND t_hlc <= @end_t_hlc";
+        }
+
+        var sql = $"""
+            SELECT COUNT(*)::INT
+            FROM scheduler.scheduler_log
+            {whereClause}
+            """;
+
+        await using var connection = await DataSource.OpenConnectionAsync(tenantId, "reader", cancellationToken)
+            .ConfigureAwait(false);
+        await using var command = CreateCommand(sql, connection);
+
+        AddParameter(command, "tenant_id", tenantId);
+        if (startTHlc is not null)
+        {
+            AddParameter(command, "start_t_hlc", startTHlc);
+        }
+        if (endTHlc is not null)
+        {
+            AddParameter(command, "end_t_hlc", endTHlc);
+        }
+
+        var result = await command.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false);
+        return result is int count ? count : 0;
+    }
+
+    private static SchedulerLogEntity MapSchedulerLogEntry(NpgsqlDataReader reader)
+    {
+        return new SchedulerLogEntity
+        {
+            SeqBigint = reader.GetInt64(reader.GetOrdinal("seq_bigint")),
+            TenantId = reader.GetString(reader.GetOrdinal("tenant_id")),
+            THlc = reader.GetString(reader.GetOrdinal("t_hlc")),
+            PartitionKey = reader.GetString(reader.GetOrdinal("partition_key")),
+            JobId = reader.GetGuid(reader.GetOrdinal("job_id")),
+            PayloadHash = reader.GetFieldValue<byte[]>(reader.GetOrdinal("payload_hash")),
+            PrevLink = reader.IsDBNull(reader.GetOrdinal("prev_link"))
+                ? null
+                : reader.GetFieldValue<byte[]>(reader.GetOrdinal("prev_link")),
+            Link = reader.GetFieldValue<byte[]>(reader.GetOrdinal("link")),
+            CreatedAt = reader.GetFieldValue<DateTimeOffset>(reader.GetOrdinal("created_at"))
+        };
+    }
+}

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/Postgres/SchedulerChainLinking.cs

@@ -0,0 +1,160 @@
+// -----------------------------------------------------------------------------
+// SchedulerChainLinking.cs
+// Sprint: SPRINT_20260105_002_002_SCHEDULER_hlc_queue_chain
+// Task: SQC-008 - Implement SchedulerChainLinking static class
+// -----------------------------------------------------------------------------
+
+using System.Security.Cryptography;
+using System.Text;
+using StellaOps.HybridLogicalClock;
+
+namespace StellaOps.Scheduler.Persistence.Postgres;
+
+/// <summary>
+/// Static utility class for computing chain links in the scheduler queue.
+/// Chain links provide tamper-evident sequence proofs per the advisory specification.
+/// </summary>
+public static class SchedulerChainLinking
+{
+    /// <summary>
+    /// Number of bytes in a chain link (SHA-256 = 32 bytes).
+    /// </summary>
+    public const int LinkSizeBytes = 32;
+
+    /// <summary>
+    /// Compute chain link per advisory specification:
+    /// link_i = Hash(link_{i-1} || job_id || t_hlc || payload_hash)
+    /// </summary>
+    /// <param name="prevLink">Previous chain link, or null for first entry (uses 32 zero bytes).</param>
+    /// <param name="jobId">Job identifier.</param>
+    /// <param name="tHlc">HLC timestamp.</param>
+    /// <param name="payloadHash">SHA-256 hash of canonical payload.</param>
+    /// <returns>New chain link (32 bytes).</returns>
+    public static byte[] ComputeLink(
+        byte[]? prevLink,
+        Guid jobId,
+        HlcTimestamp tHlc,
+        byte[] payloadHash)
+    {
+        ArgumentNullException.ThrowIfNull(payloadHash);
+        if (payloadHash.Length != LinkSizeBytes)
+        {
+            throw new ArgumentException($"Payload hash must be {LinkSizeBytes} bytes", nameof(payloadHash));
+        }
+
+        using var hasher = IncrementalHash.CreateHash(HashAlgorithmName.SHA256);
+
+        // Previous link (or 32 zero bytes for first entry)
+        hasher.AppendData(prevLink ?? new byte[LinkSizeBytes]);
+
+        // Job ID as bytes (using standard Guid byte layout)
+        hasher.AppendData(jobId.ToByteArray());
+
+        // HLC timestamp as UTF-8 bytes
+        hasher.AppendData(Encoding.UTF8.GetBytes(tHlc.ToSortableString()));
+
+        // Payload hash
+        hasher.AppendData(payloadHash);
+
+        return hasher.GetHashAndReset();
+    }
+
+    /// <summary>
+    /// Compute chain link from string HLC timestamp.
+    /// </summary>
+    public static byte[] ComputeLink(
+        byte[]? prevLink,
+        Guid jobId,
+        string tHlcString,
+        byte[] payloadHash)
+    {
+        var tHlc = HlcTimestamp.Parse(tHlcString);
+        return ComputeLink(prevLink, jobId, tHlc, payloadHash);
+    }
+
+    /// <summary>
+    /// Compute deterministic payload hash from canonical JSON.
+    /// </summary>
+    /// <param name="canonicalJson">RFC 8785 canonical JSON representation of payload.</param>
+    /// <returns>SHA-256 hash (32 bytes).</returns>
+    public static byte[] ComputePayloadHash(string canonicalJson)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(canonicalJson);
+        return SHA256.HashData(Encoding.UTF8.GetBytes(canonicalJson));
+    }
+
+    /// <summary>
+    /// Compute deterministic payload hash from raw bytes.
+    /// </summary>
+    /// <param name="payload">Payload bytes.</param>
+    /// <returns>SHA-256 hash (32 bytes).</returns>
+    public static byte[] ComputePayloadHash(byte[] payload)
+    {
+        ArgumentNullException.ThrowIfNull(payload);
+        return SHA256.HashData(payload);
+    }
+
+    /// <summary>
+    /// Verify that a chain link is correctly computed.
+    /// </summary>
+    /// <param name="expectedLink">The stored link to verify.</param>
+    /// <param name="prevLink">Previous chain link.</param>
+    /// <param name="jobId">Job identifier.</param>
+    /// <param name="tHlc">HLC timestamp.</param>
+    /// <param name="payloadHash">Payload hash.</param>
+    /// <returns>True if the link is valid.</returns>
+    public static bool VerifyLink(
+        byte[] expectedLink,
+        byte[]? prevLink,
+        Guid jobId,
+        HlcTimestamp tHlc,
+        byte[] payloadHash)
+    {
+        ArgumentNullException.ThrowIfNull(expectedLink);
+        if (expectedLink.Length != LinkSizeBytes)
+        {
+            return false;
+        }
+
+        var computed = ComputeLink(prevLink, jobId, tHlc, payloadHash);
+        return CryptographicOperations.FixedTimeEquals(expectedLink, computed);
+    }
+
+    /// <summary>
+    /// Verify that a chain link is correctly computed (string HLC version).
+    /// </summary>
+    public static bool VerifyLink(
+        byte[] expectedLink,
+        byte[]? prevLink,
+        Guid jobId,
+        string tHlcString,
+        byte[] payloadHash)
+    {
+        if (!HlcTimestamp.TryParse(tHlcString, out var tHlc))
+        {
+            return false;
+        }
+        return VerifyLink(expectedLink, prevLink, jobId, tHlc, payloadHash);
+    }
+
+    /// <summary>
+    /// Create the genesis link (first link in a chain).
+    /// Uses 32 zero bytes as the previous link.
+    /// </summary>
+    public static byte[] ComputeGenesisLink(
+        Guid jobId,
+        HlcTimestamp tHlc,
+        byte[] payloadHash)
+    {
+        return ComputeLink(null, jobId, tHlc, payloadHash);
+    }
+
+    /// <summary>
+    /// Formats a link as a hexadecimal string for display/logging.
+    /// </summary>
+    public static string ToHexString(byte[]? link)
+    {
+        if (link is null) return "(null)";
+        return Convert.ToHexString(link).ToLowerInvariant();
+    }
+}

src/Scheduler/__Libraries/StellaOps.Scheduler.Persistence/StellaOps.Scheduler.Persistence.csproj

@@ -28,7 +28,6 @@
     <ProjectReference Include="..\..\..\__Libraries\StellaOps.Infrastructure.Postgres\StellaOps.Infrastructure.Postgres.csproj" />
     <ProjectReference Include="..\..\..\__Libraries\StellaOps.Infrastructure.EfCore\StellaOps.Infrastructure.EfCore.csproj" />
     <ProjectReference Include="..\..\..\__Libraries\StellaOps.HybridLogicalClock\StellaOps.HybridLogicalClock.csproj" />
-    <ProjectReference Include="..\..\..\__Libraries\StellaOps.Canonical.Json\StellaOps.Canonical.Json.csproj" />
   </ItemGroup>
 
   <!-- Embed SQL migrations as resources -->