Repository navigation
feat(locking): the optional Goldpath.Locking.Oracle package — DBMS_LOCK through DistributedLock.Oracle (G7, O-4, #407) - #535
Conversation
…CK through DistributedLock.Oracle (G7, O-4, #407) - packages/Goldpath.Locking.Oracle: net8.0;net10.0, AddGoldpathOracleLocking<TBuilder>(configure), DistributedLock.Oracle 1.0.5 (MIT) pinned centrally, ODP.NET raised to the 23.26.301 pin and System.Security.Cryptography.Pkcs to the patched line; PublicAPI files, README, ops/locking-oracle.md (the EXECUTE ON SYS.DBMS_LOCK grant, DBA_LOCKS / V$LOCK UL, session-owned semantics, the pool). A Provider left in configuration for another store is refused. - Goldpath.Locking: GoldpathLockProvider.Oracle (= 3); AddGoldpathLocking refuses it and names the package, and refuses a value that names no provider instead of building PostgreSQL for it. - Proof: LockingRegistrationTests (3 new facts, red with the old registration); LockContractOracleTests (Category=Oracle, real Oracle Free 23.26.3): both contract facts through AddGoldpathOracleLocking in a schema granted as the runbook says, PLS-00201 without the grant, a 300-character name, the configuration refusal. Mutation: Goldpath.Locking 91.67 % -> 92.00 %. - Ledgers: Goldpath.sln, packages/README (25 packages), stryker/README, the api-review-1.0 TSV, CHANGELOG, ga-gate-status G7, RFC goldpath-locking, license-gate comment (no new exception). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AFdNbH6XCMBD3fDnStTtU
Verifier verdict (run 2026-11-07)Head verified: Verdict: changes requested. 0 BLOCKER, 1 MAJOR, 0 MINOR, 1 NIT. The package does what #407 asks. All four of the PR's red proofs reproduce, and I ran the contract on a real Oracle Free 23.26.3. I also ran the runbook's own inspection queries and a session kill, which the PR lists as not verified, and both hold. One edge case breaks the lock contract on Oracle. A name of 128 characters or fewer whose UTF-8 encoding is longer than 128 bytes is not hashed. Finding1. MAJOR: a multi-byte lock name of up to 128 characters but over 128 bytes throws on Oracle
NIT (optional)
What I checked
Deep review
Edge-case probes (throwaway facts on the real Oracle container, never pushed)
Not run: the same multi-byte name on Postgres and Redis (no containers pulled for them). Medallion's Postgres provider hashes string names to a key, so it is expected to work there. Also not run: the first OIDC publication of a new package id, which is the release owner's. Labels: Generated by Claude Code |
…heir characters (#407) Verifier finding 1 (MAJOR) on 8c0b4c5: DistributedLock.Oracle hashes a name by its CHARACTER count, and SYS.DBMS_LOCK_ALLOCATED.NAME holds 128 BYTES, so a name of at most 128 characters whose UTF-8 is longer (87 chars / 148 bytes of Turkish) threw ORA-12899 from TryAcquireLockAsync instead of returning a handle. - OracleLockNames (internal, composed inside the metered decorator) maps the name before the library sees it: an ASCII name that fits passes unchanged; any other becomes its leading printable ASCII (at most 40), '#', and the hex SHA-256 of its UTF-8 (at most 105 ASCII bytes, culture-free). An ASCII name already in that shape is hashed too, so it cannot alias another. - LockContractOracleTests: a 148-byte name is one exclusive lock, its last-character twin a second, and a 300-character multi-byte name is taken. Red with ORA-12899 without the mapping. - OracleLockNameTests (no container): pass-through, the 128/129 boundary, the exact shape, the readable-prefix stops, stand-in shapes, null, tr-TR. Red (6 facts) without the mapping. - Mutation: stryker/Goldpath.Locking.Oracle.json, scoped to OracleLockNames.cs, 100.00 % (first run 73.33 %; tests sharpened). Joins the nightly matrix (twenty-three). - Runbook sentence corrected (what is hashed, by whom); CHANGELOG, stryker/README, release-checklist, ai-sdlc-status. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AFdNZxtriHacWvR8ePyxr
|
Addressed verifier findings: MAJOR 1 (multi-byte names over 128 bytes) and NIT 1. Head is now
Runs on
Pre-PR self-check (the whole PR as it now stands):
Generated by Claude Code |
Verifier verdict (run 2026-11-07, daytime)Head verified: Verdict: no blocking findings. 0 BLOCKER, 0 MAJOR, 0 MINOR, 1 NIT. This morning's MAJOR 1 is fixed: a name over 128 UTF-8 bytes no longer throws on Oracle. NIT 1 is fixed too. What I checked
Deep review (delta)
Edge-case probes (throwaway, never pushed)
NIT (optional)
Not run: Redis and Postgres with the same multi-byte names (that path is not touched by this delta), and the first OIDC publication of a new package id, which is the release owner's. Labels: Owner: safe to merge — summary: adds the optional Generated by Claude Code |
# Conflicts: # docs/strategy/ga-gate-status.md
|
Brought up to date with main@fd5d37f. Conflicts resolved in:
I removed Generated by Claude Code |
Verifier verdict (run 2026-11-08, daytime)Head verified: Verdict: verified. 0 BLOCKER, 0 MAJOR, 0 MINOR, 0 NIT. The lone-surrogate NIT from 2026-11-07 is unchanged and optional. Tier C ( Delta since my last verdict
What I checked
Deep review (delta = merge only)
Edge-case probes (throwaway facts, never pushed): 3/3 pass
Not run: the first OIDC publication of a new package id, which belongs to the release owner. Labels: Owner: safe to merge — summary: adds the optional Generated by Claude Code |
# Conflicts: # CHANGELOG.md # docs/strategy/ga-gate-status.md
|
Brought up to date with main@543747a, as merge commit
What merged without conflicts: Build, tests and gates:
Not run here:
Generated by Claude Code |
Verifier verdict (run 2026-11-09)Head verified: Verdict: changes requested. 0 BLOCKER, 0 MAJOR, 1 MINOR, 0 NIT. Tier C, so this PR is never auto-merged.
Finding1. MINOR: on Oracle, a cancelled
Delta since my last verdict
What I checked
Deep review
Edge-case probes (throwaway facts on a real Oracle Free container, never pushed)
Not run: the first OIDC publication of a new package id (the release owner's). Labels: Generated by Claude Code |
…said and pinned (#407) Verifier finding 1 (MINOR) on fd186ca: DBMS_LOCK.REQUEST is a server-side wait DistributedLock.Oracle does not interrupt, so a cancelled acquire on a held lock returns only when its timeout ends; nothing told an operator. - ops/locking-oracle.md: "Cancellation and shutdown" — the behaviour, that Goldpath passes the token down, and what a host does about it (acquire timeouts shorter than HostOptions.ShutdownTimeout and the termination grace, or short TryAcquire slices checking the token). - README: the same, in one paragraph, linking the section. - LockContractOracleTests: a held lock, an 8 s acquire cancelled at 0.5 s, throws OperationCanceledException only after >= 6 s — so a library upgrade that starts honouring cancellation is noticed. 7/7 on Oracle Free 23.26.3. - CHANGELOG [Unreleased]: the documented behaviour and the new fact; the list's count ("Three more facts") corrected. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AFdNc7ZZ3NR3txnrDK2E7
|
Addressed verifier findings: MINOR 1 (cancellation on Oracle), the documentation fix plus the optional fact. Head is now
I made no code change to the provider. Bounding each Gates on this head (rc 0 for each): Pre-PR self-check (the whole PR as it now stands):
Generated by Claude Code |
Verifier verdict (run 2026-11-10)Head verified: Verdict: changes requested. 0 BLOCKER, 1 MAJOR (mechanical), 0 MINOR, 1 NIT. Last round's MINOR (cancellation on Oracle undocumented) is fixed, and the new fact holds on a real Oracle. What is left is a conflict with today's Finding1. MAJOR: the PR no longer merges into today's
Delta reviewed (
|
| Step | Result |
|---|---|
| 1. Scope | Only last round's finding. No code change to the provider; the "bound each slice in the decorator" design is left open, as offered. |
| 2. Ledgers | CHANGELOG [Unreleased] is updated. No deferral, so no open-threads row. |
| 3. Confidentiality | The delta: 0 hits. |
| 4. Build | Goldpath.IntegrationTests -c Release: 0 warnings, 0 errors. |
| 4. Tests | LockContractOracleTests on a real gvenzl/oracle-free container: all passed, including the new fact (8 s) and my three probes below. |
| 4. Red proof | n.a. for this delta: the fact pins the library's behaviour, so there is no fix to plant. My P2 shows the same behaviour through AcquireLockAsync, so the fact does not pass by accident. |
| 4. Gates | docs-freshness, ledger-check, schema-honesty, skills-parity, template-pins, api-review-gate, license-gate.py: all rc 0. |
5. CI on 71fd1bd |
All green, including oracle, integration, gates, kit and the GM matrix. merge-policy is red by design (Tier C without owner-approved). |
| 6. Charter | n.a. |
Deep review (delta)
| Dimension | Result | |
|---|---|---|
| a | Security | n.a. Docs and a test. |
| b | Correctness & edge cases | ✓ A token cancelled before the call is honoured at once (P1); the lock stays usable after a cancelled wait (P3). See the NIT. |
| c | Concurrency | ✓ No new shared state. |
| d | Data & migrations | n.a. |
| e | Performance | ✓ The fact costs about 8 s in the Oracle lane. |
| f | Compatibility | ✓ No API change. |
| g | Test quality | ✓ It asserts behaviour on a real server. A library upgrade that starts honouring cancellation turns it red, which is its purpose. |
| h | Code quality | ✓ The fact's summary says why it exists and what to revisit. |
| i | Observability & operability | ✓ The shutdown guidance is now where an operator looks. |
| j | Honesty | ✓ Every sentence of the new section holds against the facts and probes. Finding 1 is the conflict, not a claim. |
Edge-case probes (throwaway facts on a real Oracle Free container, reverted, never pushed)
| # | Probe | Result |
|---|---|---|
| P1 | A token cancelled before TryAcquireLockAsync is called, on a held lock |
OperationCanceledException after 2 ms. Pass, but see the NIT. |
| P2 | AcquireLockAsync (not Try…), 8 s timeout, cancelled at 0.5 s |
OperationCanceledException after 8.05 s. Pass: the doc's "TryAcquireLockAsync / AcquireLockAsync" holds for both. |
| P3 | After a cancelled wait, release the holder and acquire again | Acquired. Pass: a cancelled waiter leaves nothing behind. |
NIT (optional)
- The runbook says cancelling "does NOT return it early". P1 shows that a token that is already cancelled when the call starts is honoured at once. A short clause would stop a reader from concluding that a shutdown-time call always waits: "(a token already cancelled when the call starts is honoured at once)".
Labels: changes-requested. Only the merge with main is needed; the content is verified.
Generated by Claude Code
Conflicts were only in ledger files (CHANGELOG.md, docs/strategy, stryker/README.md) after #546 and #554 merged. Every entry from both sides is kept; where both edited one row, main's text carries this PR's own insertion. The PR's diff against main is its original diff for these files. ledger-check, docs-freshness and schema-honesty exit 0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Brought up to date with Posted by Claude Code on the owner's instruction (2026-11-10: "Evet, yap"). |
Verifier verdict (run 2026-11-10, daytime)Head verified: Verdict: changes requested. 0 BLOCKER, 1 MAJOR (mechanical), 0 MINOR, 1 NIT (carried over). This morning's conflict is resolved correctly, but Finding1. MAJOR: the PR does not merge into today's
Delta since my last verdict
What I checked
Deep review (delta = merge only; full tables in the 2026-11-07..10 verdicts)
Edge-case probes (this run)
NIT (optional, from this morning): the runbook's "does NOT return it early" could say that a token already cancelled when the call starts is honoured at once. Labels: Generated by Claude Code |
|
Brought up to date with
Generated by Claude Code |
Verifier verdict (run 2026-11-11)Head verified: Verdict: verified. 0 BLOCKER, 0 MAJOR, 0 MINOR, 1 NIT (carried over, optional). Yesterday's MAJOR (the CHANGELOG conflict) is resolved. The PR merges cleanly into today's Delta since my last verdict
What I checked
Deep review (delta = merge only)
Edge-case probes (this run)
Not run: the Oracle lock facts locally. The code is byte-identical to the head where I ran them on 2026-11-10, and CI NIT (optional, unchanged): the runbook's "does NOT return it early" could add that a token already cancelled when the call starts is honoured at once. Merge order: #529, #535, #537 and #538 all add CHANGELOG Labels: Owner: safe to merge — summary: adds the optional Generated by Claude Code |
CHANGELOG.md: both sides' [Unreleased] entries kept (Added and Changed). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018AFdNZbL5UCo9Kkefph8f3
|
Brought up to date with main@02128c5. The head is now Conflicts resolved in:
Both sides are kept verbatim, with no line dropped.
Build, tests and gates:
The PR's behaviour, API and recorded decisions are unchanged by the merge. I removed Generated by Claude Code |
# Conflicts: # CHANGELOG.md
|
Synced with The PR's own diff in every ledger file is unchanged by the resolution. These ran locally on the merged tree:
The Owner's session (Claude Code). |
Verifier verdict (run 2026-11-11, daytime)Head verified: Verdict: no findings in the PR's content. CI is red on this head, for reasons that come from What I checked on the delta
CI on
|
| Dimension | Result | |
|---|---|---|
| a | Security | n.a.: no code delta. The package pins and licence-gate exception are unchanged |
| b | Correctness & edge cases | ✓ the merge dropped no line from either side (counts above) |
| c | Concurrency | n.a.: no code delta |
| d | Data & migrations | n.a.: none touched |
| e | Performance | n.a. |
| f | Compatibility | ✓ the PublicAPI.Unshipped entries are unchanged, and GoldpathLockProvider.Oracle = 3 is additive |
| g | Test quality | ✓ the Locking suite is unchanged and 17/17. The red→green proof stands from my earlier verdicts (no code changed since) |
| h | Code quality | n.a.: no code delta |
| i | Observability | n.a. |
| j | Honesty | ✓ the CHANGELOG, ga-gate-status and stryker README rows still match the code |
Edge-case probes: none new, because the delta has no behaviour change. Instead I re-ran the one shape the merge could plausibly have broken (GmCleanFeatures, which composes Locking): GREEN.
Not run in this pass: the Oracle container lane for OracleLock* (the code is unchanged since my earlier run of it).
Generated by Claude Code
What and why
Slice O-4 of
docs/rfc/goldpath-oracle.md(§2.9, §4, §8, open question 3) adds locking on Oracle as an optional package, mirroringGoldpath.Locking.SqlServer. The owner approved the dependency on 2026-11-04 (comment on #407).packages/Goldpath.Locking.Oracle(net8.0;net10.0):AddGoldpathOracleLocking<TBuilder>(this TBuilder, Action<GoldpathLockingOptions>? configure = null);OracleDistributedSynchronizationProvider(DBMS_LOCK) behind the existingGoldpathMeteredLockProvider(ADR-0003);ConnectionNamedefaults todatabase;ops/locking-oracle.md. The runbook covers theEXECUTE ON SYS.DBMS_LOCKgrant, inspecting a held lock (DBA_LOCKS/V$LOCKtypeUL,DBMS_LOCK_ALLOCATED), session-owned semantics, and pool sizing.Pins:
DistributedLock.Oracle1.0.5 (MIT, 2026-02-14) is the newest release and more than 14 days old;[23.6.1, );System.Security.Cryptography.Pkcsto the patched 10.0.14. The first build was NU1903 red on ODP.NET's 8.0.1, and this is the same lift SqlServer's package uses.Resolved on both TFMs: DistributedLock.Core 1.0.9, ODP.NET 23.26.301, Pkcs 10.0.14.
Goldpath.Locking:GoldpathLockProvider.Oracle(= 3) is added inPublicAPI.Unshipped.txt;AddGoldpathLockingrefusesOracleat registration and names the package;SqlServerwas silently built as PostgreSQL, andOraclewould have been too.Found in self-review and refused: a
Goldpath:DistributedLocking:Providerleft in configuration for another store binds over the Oracle default, so the options would describe a lock the method does not build.AddGoldpathOracleLockingnow refuses that in words.Reproduce
A fourth plant is run through the same apply/test/restore helper.
AddGoldpathOracleLockinggets a provider that salts every name with a fresh GUID, so the lock is not exclusive. ThenExactly_one_competitor_holds_the_lock_and_release_hands_it_overreports Failed: 1.Acceptance criteria (#407)
packages/Goldpath.Locking.Oraclemirrors SqlServer:net8.0;net10.0;Goldpath.LockingandDistributedLock.Oracle, pinned centrally at 1.0.5. The pin and its date are in a comment inDirectory.Packages.props;Descriptionstates FUTC and why the package is separate;ops/locking-oracle.mdcoversDBMS_LOCK/V$LOCK, session-owned semantics, and theEXECUTE ON DBMS_LOCKgrant.AddGoldpathOracleLocking<TBuilder>(…);GoldpathLockProvider.Oracle = 3, appended inGoldpath.Locking's Unshipped file.Provider = OracleonAddGoldpathLockingthrows and namesGoldpath.Locking.OracleandAddGoldpathOracleLocking(). Unit facts cover both code and configuration.Category=Oracle: bothLockContractTestsfacts pass throughAddGoldpathOracleLocking. The test grantsEXECUTE ON SYS.DBMS_LOCKas SYSDBA, with the runbook's statement verbatim.Goldpath.*, only this package references ODP.NET.license-gate.pyis GREEN (354 packages) with no new exception; only its comment changes, from "if O-4 ships it" to "O-4, G7 Oracle 4/12: Ship the optional Goldpath.Locking.Oracle package (DBMS_LOCK via DistributedLock.Oracle) #407".Goldpath.sln, in the same solution folder;release.ymlpackspackages/*/*.csproj, so nothing to add there;packages/README.mdsays 25 packages, the train 24, and names the two optional Locking providers. That README has no Ring B row to extend, so the providers are named in its train sentence instead;docs-freshness.shis green;stryker/README.md"Packages without a gate" names it, and says its proof is the Oracle lane rather than a unit suite.[Unreleased]: under Added (the package), and under Changed (the stricter registration).Pre-PR self-check
Ledgers:
docs/rfc/goldpath-locking.md§8, with an Oracle line beside the SqlServer D2 amendment;stryker/README.md: Packages without a gate, the Locking score row (91.67 % → 92.00 %, re-measured), and a re-measure paragraph;docs/strategy/api-review-1.0/Goldpath.Locking.Oracle.tsv. It has the header only, like SqlServer's, becauseapi-review-gate.shrefuses a package with a ledger and no TSV. Not done here: the verdict rows for the 3 new live lines (2 here, 1 in Locking). They are G4's review, and--require-completewill list them.goldpath-ga-readiness.mdare untouched.XML docs: the enum member's
///sits on the new member, afterSqlServer's declaration. Nothing is inserted between an existing doc comment and its member.Honesty: every runbook claim that the tests can reach was measured:
PLS-00201without it;The
DBA_LOCKS/V$LOCKinspection queries were not run (see Not verified).Wired: the contract runs through
AddGoldpathOracleLockingon a host, and asserts that the options sayOracleand that the provider is the metered decorator.Contracts: the PublicAPI files match the code (the analyzer builds clean with warnings as errors).
Deep self-review:
dotnet list package --vulnerable --include-transitiveis clean on the new project;Gates run (all rc 0)
dotnet build Goldpath.sln -c Releasedotnet format --verify-no-changes(touched projects / file)python3 scripts/license-gate.py./scripts/api-review-gate.shand--selftestpython3 scripts/merge-tier.py selftest,engine-gate.shdocs-freshness.sh(25 packages),schema-honesty.sh,skills-parity.sh,template-pins.sh,ledger-check.sh*./scripts/mutation-gate.sh Goldpath.Locking*
ledger-check.shran through a shim that answers onlygh auth status, which fails behind this session's proxy whilegh apiworks.Not verified
DBA_LOCKS/V$LOCK/DBMS_LOCK_ALLOCATEDqueries were not run against the container. They are written from Oracle's documented views.Closes #407
Generated by Claude Code