@learncard/credential-library 2.0.1 → 2.0.2

package/dist/fixtures/clr/provisional-transcript.d.ts

@@ -0,0 +1,38 @@
+import { type UnsignedVC } from '@learncard/types';
+import type { CredentialFixture } from '../../types';
+/**
+ * Provisional CLR 2.0 transcript with a `LearnCardCredentialRefresh2026` service, built for
+ * the managed credential refresh flow (LC-2117 / LC-2135 / LC-2136).
+ *
+ * The credential starts as a provisional transcript; `buildFinalTranscriptVariant`
+ * produces the final variant WITHOUT changing the credential ID, issuer, or subject,
+ * mirroring a registrar publishing the finalized record to the same refresh service.
+ *
+ * JSON-LD note: neither the VCDM 1.1/2.0 nor the live OBv3/CLR contexts define the
+ * term `LearnCardCredentialRefresh2026` (or the LearnCard `authorization` extension), so
+ * the fixture carries an inline context fragment — DIDKit's data-loss detection
+ * otherwise refuses to sign.
+ */
+/** Inline JSON-LD context fragment defining the refresh-service terms inline. */
+export declare const REFRESH_SERVICE_INLINE_CONTEXT: {
+    readonly LearnCardCredentialRefresh2026: "https://learncard.com/refresh#LearnCardCredentialRefresh2026";
+    readonly authorization: {
+        readonly '@id': "https://purl.imsglobal.org/spec/ob/v3p0#authorization";
+        readonly '@context': {
+            readonly LearnCardDIDAuth: "https://docs.learncard.com/definitions#LearnCardDIDAuth";
+        };
+    };
+};
+export declare const clrProvisionalTranscript: CredentialFixture;
+/**
+ * Builds the final transcript variant from a prepared provisional credential.
+ *
+ * Preserves the credential ID, issuer, subject, and refresh service (identity
+ * invariants the managed refresh pipeline enforces) while flipping user-visible
+ * content to its final state: name/description become final, the nested course
+ * credential shows the completed result, and `validFrom` moves forward.
+ */
+export declare const buildFinalTranscriptVariant: (provisional: UnsignedVC, options?: {
+    validFrom?: string;
+}) => UnsignedVC;
+//# sourceMappingURL=provisional-transcript.d.ts.map

package/dist/fixtures/clr/provisional-transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisional-transcript.d.ts","sourceRoot":"","sources":["../../../src/fixtures/clr/provisional-transcript.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;;;;;GAYG;AAEH,iFAAiF;AACjF,eAAO,MAAM,8BAA8B;;;;;;;;CASjC,CAAC;AAaX,eAAO,MAAM,wBAAwB,EAAE,iBAoGtC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,GACpC,aAAa,UAAU,EACvB,UAAS;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,KACrC,UAsCF,CAAC"}

package/dist/fixtures/index.d.ts

@@ -38,8 +38,9 @@ import { vcV2LicenseCredential } from './vc-v2/license-credential';
 import { clrGreatPlainsFull } from './clr/great-plains-full';
 import { clrWestbridgeFull } from './clr/westbridge-full';
 import { clrCompetencyAligned } from './clr/competency-aligned';
+import { clrProvisionalTranscript, buildFinalTranscriptVariant, REFRESH_SERVICE_INLINE_CONTEXT } from './clr/provisional-transcript';
 import { clrDemoIsdDiplomaAssessments } from './clr/demo-isd-diploma-assessments';
 import { sdJwtVcCourseCompletion } from './sd-jwt-vc/course-completion';
 export declare const ALL_FIXTURES: LibraryFixture[];
-export { vcV1Basic, vcV1WithStatus, vcV2Basic, vcV2WithEvidence, vcV2MultipleSubjects, vcV2RenderMethodExample, obv3MinimalBadge, obv3FullBadge, obv3WithAlignment, obv3WithEndorsement, obv3PlugfestJff2, clrMinimal, clrMultiAchievement, boostBasic, boostId, boostWithSkills, invalidMissingContext, invalidEmptyType, invalidMissingIssuer, clrNdStudentTranscript, obv3OneedtechFull, obv3ProfessionalCert, obv3MicroCredential, obv3CourseCompletion, obv3StandaloneFullCourse, obv3K12Diploma, obv3EndorsementCredential, clrUniversityTranscript, boostCommunityAward, boostDelegate, vcV1AlumniCredential, vcV2EmploymentCredential, vcV2EducationDegree, vcV2DigitalId, vcV2MembershipCredential, vcV2LicenseCredential, clrGreatPlainsFull, clrWestbridgeFull, clrCompetencyAligned, clrDemoIsdDiplomaAssessments, sdJwtVcCourseCompletion, };
+export { vcV1Basic, vcV1WithStatus, vcV2Basic, vcV2WithEvidence, vcV2MultipleSubjects, vcV2RenderMethodExample, obv3MinimalBadge, obv3FullBadge, obv3WithAlignment, obv3WithEndorsement, obv3PlugfestJff2, clrMinimal, clrMultiAchievement, boostBasic, boostId, boostWithSkills, invalidMissingContext, invalidEmptyType, invalidMissingIssuer, clrNdStudentTranscript, obv3OneedtechFull, obv3ProfessionalCert, obv3MicroCredential, obv3CourseCompletion, obv3StandaloneFullCourse, obv3K12Diploma, obv3EndorsementCredential, clrUniversityTranscript, boostCommunityAward, boostDelegate, vcV1AlumniCredential, vcV2EmploymentCredential, vcV2EducationDegree, vcV2DigitalId, vcV2MembershipCredential, vcV2LicenseCredential, clrGreatPlainsFull, clrWestbridgeFull, clrCompetencyAligned, clrProvisionalTranscript, buildFinalTranscriptVariant, REFRESH_SERVICE_INLINE_CONTEXT, clrDemoIsdDiplomaAssessments, sdJwtVcCourseCompletion, };
 //# sourceMappingURL=index.d.ts.map

package/dist/fixtures/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fixtures/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fixtures/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/credential-library",
-    "version": "2.0.1",
+    "version": "2.0.2",
     "description": "Comprehensive library of Verifiable Credential fixtures for testing, development, and regression prevention across the VC ecosystem",
     "main": "./dist/index.js",
     "module": "./dist/credential-library.esm.js",
@@ -26,8 +26,8 @@
         "url": "https://github.com/learningeconomy/LearnCard/issues"
     },
     "devDependencies": {
-        "@learncard/didkit-plugin": "1.9.13",
-        "@learncard/init": "2.4.14",
+        "@learncard/didkit-plugin": "1.9.14",
+        "@learncard/init": "2.4.15",
         "@types/node": "^17.0.38",
         "esbuild": "^0.27.1",
         "jose": "^5.9.6",
@@ -36,8 +36,8 @@
         "vitest": "4.1.10"
     },
     "dependencies": {
-        "@learncard/sd-jwt-vc-plugin": "0.2.11",
-        "@learncard/types": "5.18.3",
+        "@learncard/sd-jwt-vc-plugin": "0.2.12",
+        "@learncard/types": "5.19.0",
         "@sd-jwt/sd-jwt-vc": "^0.19.0",
         "zod": "4.1.13"
     },

package/src/__tests__/docs-json.test.ts

@@ -0,0 +1,148 @@
+import { readFileSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { fileURLToPath } from 'url';
+
+import { beforeAll, describe, expect, it } from 'vitest';
+import { initLearnCard, type LearnCardFromSeed } from '@learncard/init';
+import { AlignmentValidator, LCNBoostStatus, UnsignedVCValidator } from '@learncard/types';
+
+const didkit = readFile(
+    require.resolve('@learncard/didkit-plugin/dist/didkit/didkit_wasm_bg.wasm')
+);
+
+// `initLearnCard` is overloaded; `ReturnType` would pick the no-arg EmptyLearnCard overload.
+let wallet: LearnCardFromSeed['returnValue'];
+let subjectDid: string;
+
+beforeAll(async () => {
+    wallet = await initLearnCard({ seed: 'a'.repeat(64), didkit, allowRemoteContexts: true });
+    const recipient = await initLearnCard({
+        seed: 'b'.repeat(64),
+        didkit,
+        allowRemoteContexts: true,
+    });
+    subjectDid = recipient.id.did();
+}, 30_000);
+
+const docsRoot = new URL('../../../../docs/', import.meta.url);
+const summary = readFileSync(new URL('SUMMARY.md', docsRoot), 'utf8');
+const section = summary.match(/^## 🧠 Understand\s*$([\s\S]*?)^## 📖 Reference\s*$/m)?.[1];
+if (!section) throw new Error('docs/SUMMARY.md: missing Understand / Reference boundaries');
+const pages = [...new Set([...section.matchAll(/\(([^)]+\.md)\)/g)].map(match => match[1]!))];
+if (!pages.length) throw new Error('docs/SUMMARY.md: Understand has no Markdown links');
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const entries = (value: unknown): unknown[] => (Array.isArray(value) ? value : [value]);
+
+// Ignore ellipses within ordinary strings (including URL paths), but not an exact "..." value.
+const isIllustrative = (source: string): boolean =>
+    source.includes('…') ||
+    [...source.matchAll(/"(?:\\.|[^"\\])*"|(\.\.\.)/g)].some(
+        match => match[0] === '"..."' || Boolean(match[1])
+    );
+
+/** Check fragment fields wherever they occur, including inside achievement subjects. */
+const validateFragments = (value: unknown): void => {
+    if (Array.isArray(value)) {
+        value.forEach(validateFragments);
+        return;
+    }
+    if (!isObject(value)) return;
+
+    if ('credentialStatus' in value) {
+        for (const entry of entries(value.credentialStatus)) {
+            expect(entry).toEqual(
+                expect.objectContaining({
+                    type: 'BitstringStatusListEntry',
+                    statusPurpose: expect.stringMatching(/^(revocation|suspension)$/),
+                    statusListIndex: expect.any(String),
+                    statusListCredential: expect.any(String),
+                })
+            );
+        }
+    }
+    if ('alignment' in value) {
+        expect(Array.isArray(value.alignment)).toBe(true);
+        for (const entry of entries(value.alignment)) {
+            AlignmentValidator.parse(entry);
+            expect(entry).toEqual(
+                expect.objectContaining({
+                    type: expect.arrayContaining(['Alignment']),
+                    targetName: expect.any(String),
+                    targetUrl: expect.any(String),
+                })
+            );
+        }
+    }
+    if (
+        'status' in value &&
+        !('credentialSubject' in value) &&
+        !isObject(value.status) &&
+        !Array.isArray(value.status)
+    ) {
+        LCNBoostStatus.parse(value.status);
+    }
+    Object.values(value).forEach(validateFragments);
+};
+
+describe('Understand documentation JSON', () => {
+    for (const page of pages) {
+        const markdown = readFileSync(fileURLToPath(new URL(page, docsRoot)), 'utf8');
+        // Match complete fences first so json-looking text inside another fence is not tested.
+        const fences = /^[ \t]{0,3}(`{3,}|~{3,})([^\r\n]*)\r?\n([\s\S]*?)^[ \t]{0,3}\1[ \t]*\r?$/gm;
+        for (const match of markdown.matchAll(fences)) {
+            if (match[2]!.trim() !== 'json') continue;
+            const source = match[3]!;
+            const line = markdown.slice(0, match.index).split('\n').length;
+            const location = `${page}:${line}`;
+
+            it(`${location} parses`, () => {
+                expect(() => JSON.parse(source)).not.toThrow();
+            });
+
+            // Parsing failures belong to the named parse test, not suite collection.
+            let parsed: unknown;
+            try {
+                parsed = JSON.parse(source);
+            } catch {
+                continue;
+            }
+            if (isIllustrative(source) || !isObject(parsed)) continue;
+            // Subject-only examples are fragments; credential-level markers must not
+            // silently become fragments when their context or type is malformed.
+            const credential =
+                '@context' in parsed ||
+                ('credentialSubject' in parsed && ('type' in parsed || 'issuer' in parsed));
+
+            if (credential) {
+                it(`${location} validates and issues`, async () => {
+                    const prepared = JSON.parse(
+                        source.includes('{{')
+                            ? source.replace(/\{\{[^{}]+\}\}/g, 'Example')
+                            : source
+                    );
+                    expect(prepared['@context']).toEqual(expect.any(Array));
+                    expect(prepared.type).toEqual(expect.arrayContaining(['VerifiableCredential']));
+                    prepared.issuer = wallet.id.did();
+                    for (const subject of entries(prepared.credentialSubject)) {
+                        if (isObject(subject)) subject.id ??= subjectDid;
+                    }
+                    const isVcV2 = (prepared['@context'] as unknown[]).some(
+                        ctx => ctx === 'https://www.w3.org/ns/credentials/v2'
+                    );
+                    const dateField = isVcV2 ? 'validFrom' : 'issuanceDate';
+                    prepared[dateField] ??= new Date().toISOString();
+                    // Docs omit issuer/date intentionally: these are supplied during issuance.
+                    const unsigned = UnsignedVCValidator.parse(prepared);
+                    validateFragments(prepared);
+                    const signed = await wallet.invoke.issueCredential(unsigned);
+                    expect(signed.proof).toBeDefined();
+                }, 15_000);
+            } else {
+                it(`${location} validates fragment fields`, () => validateFragments(parsed));
+            }
+        }
+    }
+});

package/src/__tests__/issuance.test.ts

@@ -4,7 +4,13 @@ import { describe, it, expect, beforeAll } from 'vitest';
 
 import { initLearnCard } from '@learncard/init';
 
-import { getAllFixtures, getFixture, isCredentialFixture, prepareFixture } from '../index';
+import {
+    getAllFixtures,
+    getFixture,
+    isCredentialFixture,
+    prepareFixture,
+    buildFinalTranscriptVariant,
+} from '../index';
 
 import type { CredentialFixture } from '../types';
 
@@ -69,4 +75,28 @@ describe('Credential issuance', () => {
 
         expect(signed.proof).toBeDefined();
     }, 30_000);
+
+    it('issues the provisional transcript fixture and its final variant without remote contexts', async () => {
+        const offlineWallet = await initLearnCard({
+            seed: 'c'.repeat(64),
+            didkit,
+            allowRemoteContexts: false,
+        });
+
+        const provisional = prepareFixture(getFixture('clr/provisional-transcript'), {
+            issuerDid: offlineWallet.id.did(),
+            subjectDid: 'did:example:test-subject-123',
+        });
+        const signedProvisional = await offlineWallet.invoke.issueCredential(provisional);
+
+        expect(signedProvisional.proof).toBeDefined();
+
+        const final = buildFinalTranscriptVariant(provisional, {
+            validFrom: new Date().toISOString(),
+        });
+        const signedFinal = await offlineWallet.invoke.issueCredential(final);
+
+        expect(signedFinal.proof).toBeDefined();
+        expect(signedFinal.id).toBe(signedProvisional.id);
+    }, 30_000);
 });

package/src/__tests__/registry.test.ts

@@ -17,6 +17,7 @@ import {
     registerFixtures,
     prepareFixture,
     prepareFixtureById,
+    buildFinalTranscriptVariant,
 } from '../index';
 
 import { ALL_FIXTURES } from '../fixtures';
@@ -171,6 +172,65 @@ describe('Query API', () => {
         expect(() => getFixture('nonexistent/fixture')).toThrow('not found');
     });
 
+    // -----------------------------------------------------------------------
+    // Provisional transcript fixture (LC-2117 / LC-2135 / LC-2136)
+    // -----------------------------------------------------------------------
+
+    describe('clr/provisional-transcript', () => {
+        it('is discoverable as a valid CLR 2.0 fixture with a LearnCard managed refresh service', () => {
+            const fixture = getFixture('clr/provisional-transcript');
+
+            expect(isCredentialFixture(fixture)).toBe(true);
+            expect(fixture.spec).toBe('clr-v2');
+            expect(fixture.profile).toBe('learner-record');
+            expect(fixture.validity).toBe('valid');
+            expect(fixture.features).toContain('refresh-service');
+
+            if (!isCredentialFixture(fixture)) throw new Error('Expected W3C VC fixture');
+
+            const refreshService = (
+                fixture.credential as { refreshService?: { type?: unknown; id?: unknown } }
+            ).refreshService;
+
+            expect(refreshService?.type).toBe('LearnCardCredentialRefresh2026');
+            expect(typeof refreshService?.id).toBe('string');
+        });
+
+        it('prepares provisional and final variants sharing one credential ID, issuer, and subject', () => {
+            const provisional = prepareFixtureById('clr/provisional-transcript', {
+                issuerDid: 'did:example:test-issuer',
+                subjectDid: 'did:example:test-holder',
+            });
+
+            expect(typeof provisional.id).toBe('string');
+            expect(provisional.name).toContain('Provisional');
+
+            const final = buildFinalTranscriptVariant(provisional, {
+                validFrom: '2026-06-01T00:00:00Z',
+            });
+            const provisionalIssuer =
+                typeof provisional.issuer === 'string' ? provisional.issuer : provisional.issuer.id;
+            const finalIssuer = typeof final.issuer === 'string' ? final.issuer : final.issuer.id;
+            const provisionalSubject = Array.isArray(provisional.credentialSubject)
+                ? provisional.credentialSubject[0]
+                : provisional.credentialSubject;
+            const finalSubject = Array.isArray(final.credentialSubject)
+                ? final.credentialSubject[0]
+                : final.credentialSubject;
+
+            // Identity stability: the final version shares the credential ID, issuer,
+            // and subject with the provisional version.
+            expect(final.id).toBe(provisional.id);
+            expect(finalIssuer).toBe(provisionalIssuer);
+            expect(finalSubject?.id).toBe(provisionalSubject?.id);
+
+            // The final variant is materially different and marked final.
+            expect(final.name).toContain('Final');
+            expect(final.validFrom).toBe('2026-06-01T00:00:00Z');
+            expect(final.refreshService).toEqual(provisional.refreshService);
+        });
+    });
+
     it('findFixture returns undefined for unknown ID', () => {
         expect(findFixture('nonexistent/fixture')).toBeUndefined();
     });
@@ -528,8 +588,7 @@ describe('prepareFixture', () => {
             ? (programAchievement?.resultDescription as UnknownArrayRecord[])
             : [];
         const programResultDescriptionId = programResults[0]?.resultDescription as
-            | string
-            | undefined;
+            string | undefined;
         const programResultDescription = programResultDescriptions[0]?.id as string | undefined;
 
         expect(programResultDescriptionId).toBe(programResultDescription);

package/src/fixtures/clr/provisional-transcript.ts

@@ -0,0 +1,193 @@
+import { UnsignedClrCredentialValidator, type UnsignedVC } from '@learncard/types';
+
+import type { CredentialFixture } from '../../types';
+
+/**
+ * Provisional CLR 2.0 transcript with a `LearnCardCredentialRefresh2026` service, built for
+ * the managed credential refresh flow (LC-2117 / LC-2135 / LC-2136).
+ *
+ * The credential starts as a provisional transcript; `buildFinalTranscriptVariant`
+ * produces the final variant WITHOUT changing the credential ID, issuer, or subject,
+ * mirroring a registrar publishing the finalized record to the same refresh service.
+ *
+ * JSON-LD note: neither the VCDM 1.1/2.0 nor the live OBv3/CLR contexts define the
+ * term `LearnCardCredentialRefresh2026` (or the LearnCard `authorization` extension), so
+ * the fixture carries an inline context fragment — DIDKit's data-loss detection
+ * otherwise refuses to sign.
+ */
+
+/** Inline JSON-LD context fragment defining the refresh-service terms inline. */
+export const REFRESH_SERVICE_INLINE_CONTEXT = {
+    'LearnCardCredentialRefresh2026':
+        'https://learncard.com/refresh#LearnCardCredentialRefresh2026',
+    authorization: {
+        '@id': 'https://purl.imsglobal.org/spec/ob/v3p0#authorization',
+        '@context': {
+            LearnCardDIDAuth: 'https://docs.learncard.com/definitions#LearnCardDIDAuth',
+        },
+    },
+} as const;
+
+/**
+ * Placeholder refresh service on the unsigned fixture. Callers preparing the fixture
+ * for managed issuance replace `refreshService` with the allocated service descriptor
+ * (the allocated ID is only known after `allocateCredentialRefresh`).
+ */
+const PLACEHOLDER_REFRESH_SERVICE = {
+    id: 'https://refresh.example.com/refresh/placeholder',
+    type: 'LearnCardCredentialRefresh2026',
+    authorization: { type: 'LearnCardDIDAuth' },
+} as const;
+
+export const clrProvisionalTranscript: CredentialFixture = {
+    id: 'clr/provisional-transcript',
+    name: 'Provisional Transcript (Refreshable)',
+    description:
+        'A CLR v2 provisional transcript carrying a LearnCardCredentialRefresh2026 service. Paired with buildFinalTranscriptVariant, it demonstrates the managed provisional-to-final credential refresh flow.',
+    spec: 'clr-v2',
+    profile: 'learner-record',
+    features: ['refresh-service', 'results'],
+    source: 'synthetic',
+    signed: false,
+    validity: 'valid',
+    validator: UnsignedClrCredentialValidator,
+    tags: ['transcript', 'provisional', 'refresh', 'clr', 'managed-refresh'],
+
+    credential: {
+        '@context': [
+            'https://www.w3.org/ns/credentials/v2',
+            'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json',
+            'https://purl.imsglobal.org/spec/clr/v2p0/context.json',
+            REFRESH_SERVICE_INLINE_CONTEXT,
+        ],
+        id: 'urn:uuid:7d2e9f41-3c58-4e21-9b6a-1f0c5d8e2a47',
+        type: ['VerifiableCredential', 'ClrCredential'],
+        name: 'Provisional Transcript — Ridgeview Community College',
+        description:
+            'Provisional record of courses completed to date. This transcript becomes final once the registrar certifies the completed term.',
+        issuer: {
+            id: 'did:web:registrar.ridgeview-example.edu',
+            type: ['Profile'],
+            name: 'Ridgeview Community College — Office of the Registrar',
+        },
+        validFrom: '2026-01-15T00:00:00Z',
+        refreshService: PLACEHOLDER_REFRESH_SERVICE,
+        credentialSubject: {
+            id: 'did:example:student-ridgeview-042',
+            type: ['ClrSubject'],
+            achievement: [
+                {
+                    id: 'urn:uuid:7d2e9f41-3c58-4e21-9b6a-1f0c5d8e2a48',
+                    type: ['Achievement'],
+                    achievementType: 'Course',
+                    name: 'BIO 150 — Principles of Biology',
+                    description:
+                        'Introductory biology covering cell structure, genetics, and evolution.',
+                    criteria: { narrative: 'Complete all coursework and the final exam.' },
+                    humanCode: 'BIO-150',
+                    fieldOfStudy: 'Biology',
+                    creditsAvailable: 4,
+                    resultDescription: [
+                        {
+                            id: 'urn:uuid:7d2e9f41-3c58-4e21-9b6a-1f0c5d8e2a49',
+                            type: ['ResultDescription'],
+                            name: 'Course Status',
+                            resultType: 'RawScore',
+                        },
+                    ],
+                },
+            ],
+            verifiableCredential: [
+                {
+                    '@context': [
+                        'https://www.w3.org/ns/credentials/v2',
+                        'https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json',
+                    ],
+                    id: 'urn:uuid:7d2e9f41-3c58-4e21-9b6a-1f0c5d8e2a50',
+                    type: ['VerifiableCredential', 'AchievementCredential'],
+                    name: 'BIO 150 — Principles of Biology (In Progress)',
+                    issuer: {
+                        id: 'did:web:registrar.ridgeview-example.edu',
+                        type: ['Profile'],
+                        name: 'Ridgeview Community College',
+                    },
+                    validFrom: '2026-01-15T00:00:00Z',
+                    credentialSubject: {
+                        id: 'did:example:student-ridgeview-042',
+                        type: ['AchievementSubject'],
+                        achievement: {
+                            id: 'urn:uuid:7d2e9f41-3c58-4e21-9b6a-1f0c5d8e2a48',
+                            type: ['Achievement'],
+                            achievementType: 'Course',
+                            name: 'BIO 150 — Principles of Biology',
+                            criteria: {
+                                narrative: 'Complete all coursework and the final exam.',
+                            },
+                            humanCode: 'BIO-150',
+                            fieldOfStudy: 'Biology',
+                            creditsAvailable: 4,
+                        },
+                        result: [
+                            {
+                                type: ['Result'],
+                                resultDescription: 'urn:uuid:7d2e9f41-3c58-4e21-9b6a-1f0c5d8e2a49',
+                                status: 'InProgress',
+                            },
+                        ],
+                    },
+                },
+            ],
+        },
+    },
+};
+
+/**
+ * Builds the final transcript variant from a prepared provisional credential.
+ *
+ * Preserves the credential ID, issuer, subject, and refresh service (identity
+ * invariants the managed refresh pipeline enforces) while flipping user-visible
+ * content to its final state: name/description become final, the nested course
+ * credential shows the completed result, and `validFrom` moves forward.
+ */
+export const buildFinalTranscriptVariant = (
+    provisional: UnsignedVC,
+    options: { validFrom?: string } = {}
+): UnsignedVC => {
+    const isRecord = (value: unknown): value is Record<string, unknown> =>
+        typeof value === 'object' && value !== null;
+
+    const final = JSON.parse(JSON.stringify(provisional)) as Record<string, unknown>;
+
+    final.name = 'Final Official Transcript — Ridgeview Community College';
+    final.description =
+        'Final official transcript certified by the registrar. Supersedes the provisional record.';
+
+    if (options.validFrom) final.validFrom = options.validFrom;
+
+    const subject = final.credentialSubject;
+
+    if (isRecord(subject) && Array.isArray(subject.verifiableCredential)) {
+        subject.verifiableCredential = subject.verifiableCredential.map((nested: unknown) => {
+            if (!isRecord(nested)) return nested;
+
+            const next = { ...nested };
+
+            if (typeof next.name === 'string') {
+                next.name = next.name.replace('(In Progress)', '(Completed)');
+            }
+
+            if (isRecord(next.credentialSubject) && Array.isArray(next.credentialSubject.result)) {
+                next.credentialSubject = {
+                    ...next.credentialSubject,
+                    result: next.credentialSubject.result.map((result: unknown) =>
+                        isRecord(result) ? { ...result, status: 'Completed', value: 'A' } : result
+                    ),
+                };
+            }
+
+            return next;
+        });
+    }
+
+    return final as unknown as UnsignedVC;
+};

package/src/fixtures/index.ts

@@ -56,6 +56,11 @@ import { vcV2LicenseCredential } from './vc-v2/license-credential';
 import { clrGreatPlainsFull } from './clr/great-plains-full';
 import { clrWestbridgeFull } from './clr/westbridge-full';
 import { clrCompetencyAligned } from './clr/competency-aligned';
+import {
+    clrProvisionalTranscript,
+    buildFinalTranscriptVariant,
+    REFRESH_SERVICE_INLINE_CONTEXT,
+} from './clr/provisional-transcript';
 import { clrDemoIsdDiplomaAssessments } from './clr/demo-isd-diploma-assessments';
 
 // SD-JWT VC
@@ -120,6 +125,7 @@ export const ALL_FIXTURES: LibraryFixture[] = [
     clrGreatPlainsFull,
     clrWestbridgeFull,
     clrCompetencyAligned,
+    clrProvisionalTranscript,
     clrDemoIsdDiplomaAssessments,
 
     // SD-JWT VC
@@ -167,6 +173,9 @@ export {
     clrGreatPlainsFull,
     clrWestbridgeFull,
     clrCompetencyAligned,
+    clrProvisionalTranscript,
+    buildFinalTranscriptVariant,
+    REFRESH_SERVICE_INLINE_CONTEXT,
     clrDemoIsdDiplomaAssessments,
     sdJwtVcCourseCompletion,
 };