@learncard/learn-cloud-service 2.5.34 → 2.5.36

package/src/accesslayer/share-content/delete.ts

@@ -0,0 +1,124 @@
+import type { Collection } from 'mongodb';
+
+import type { MongoShareContentDocument } from '@models';
+
+import {
+    MAX_SHARE_CONTENT_ATTEMPTS,
+    bindingMatchesDocument,
+    parseShareContentBinding,
+    shareContentBindingFilter,
+    shareContentIdentityFilter,
+    toTombstoneSummary,
+} from './internal';
+import type { ShareContentRepositoryResult, ShareContentTombstoneSummary } from './types';
+
+/**
+ * Atomically tombstone the exact object.
+ *
+ * The active -> tombstone transition is a single atomic `findOneAndUpdate` that
+ * also removes the ciphertext/recovery fields, so once it returns the payload is
+ * gone. If the identity does not exist yet, a tombstone is inserted with an
+ * atomic `$setOnInsert` upsert (delete-before-put), so a late concurrent put can
+ * never resurrect the identity. The loop only re-runs when a racing writer
+ * changed the document between the two atomic steps; active documents are
+ * otherwise immutable and tombstones are permanent, so it always settles.
+ *
+ * A binding mismatch (including another owner's object at the same identity)
+ * never modifies the stored document and returns `BINDING_MISMATCH`.
+ */
+export const deleteShareContent = async (
+    collection: Collection<MongoShareContentDocument>,
+    rawBinding: unknown
+): Promise<ShareContentRepositoryResult<ShareContentTombstoneSummary>> => {
+    const binding = parseShareContentBinding(rawBinding);
+
+    if (binding === null) return { ok: false, error: 'INVALID_INPUT' };
+
+    const exactFilter = shareContentBindingFilter(binding);
+    const identityFilter = shareContentIdentityFilter(binding);
+
+    for (let attempt = 0; attempt < MAX_SHARE_CONTENT_ATTEMPTS; attempt += 1) {
+        // 1. Atomic active -> tombstone, dropping the payload in the same update.
+        const deletedAt = new Date();
+
+        const replaced = await collection.findOneAndUpdate(
+            { ...exactFilter, kind: 'active' },
+            {
+                $set: { kind: 'tombstone', deletedAt },
+                $unset: {
+                    payloadHash: '',
+                    envelope: '',
+                    ownerEncryptedRecovery: '',
+                    ciphertextBytes: '',
+                    recoveryBytes: '',
+                    createdAt: '',
+                },
+            },
+            { returnDocument: 'after' }
+        );
+
+        if (replaced !== null) {
+            if (replaced.kind === 'tombstone') {
+                return { ok: true, value: toTombstoneSummary(replaced) };
+            }
+
+            // Unreachable under the `kind: 'active'` filter; a racing writer
+            // changed the document. Re-classify rather than trust the shape.
+            continue;
+        }
+
+        // 2. Delete-before-put: create a permanent tombstone only if absent.
+        const inserted = await collection.updateOne(
+            identityFilter,
+            {
+                $setOnInsert: {
+                    kind: 'tombstone',
+                    namespace: binding.namespace,
+                    ownerProfileId: binding.ownerProfileId,
+                    shareId: binding.shareId,
+                    contentVersion: binding.contentVersion,
+                    objectId: binding.objectId,
+                    operationId: binding.operationId,
+                    deletedAt,
+                },
+            },
+            { upsert: true }
+        );
+
+        if (inserted.upsertedCount === 1) {
+            return {
+                ok: true,
+                value: {
+                    kind: 'tombstone',
+                    namespace: binding.namespace,
+                    ownerProfileId: binding.ownerProfileId,
+                    shareId: binding.shareId,
+                    contentVersion: binding.contentVersion,
+                    objectId: binding.objectId,
+                    operationId: binding.operationId,
+                    deletedAt,
+                },
+            };
+        }
+
+        // 3. The identity exists but was not replaced: classify and fail closed.
+        const existing = await collection.findOne(identityFilter);
+
+        if (existing === null) continue;
+
+        if (existing.kind === 'tombstone') {
+            return bindingMatchesDocument(existing, binding)
+                ? { ok: true, value: toTombstoneSummary(existing) }
+                : { ok: false, error: 'BINDING_MISMATCH' };
+        }
+
+        if (!bindingMatchesDocument(existing, binding)) {
+            return { ok: false, error: 'BINDING_MISMATCH' };
+        }
+
+        // Exact active document: a concurrent writer slipped in between the two
+        // atomic steps; retry the replacement.
+    }
+
+    return { ok: false, error: 'CONFLICT' };
+};

package/src/accesslayer/share-content/index.ts

@@ -0,0 +1,70 @@
+import type { Collection, Db } from 'mongodb';
+
+import {
+    SHARE_CONTENT_COLLECTION,
+    type MongoShareContentDocument,
+    type ShareContentObjectBinding,
+    type ShareContentPutInput,
+} from '@models';
+
+import { deleteShareContent } from './delete';
+import { ensureShareContentIndexes } from './initialize';
+import { putShareContent } from './put';
+import { getShareContentContent, getShareContentRecovery, statShareContent } from './read';
+import { ShareContentRepositoryNotInitializedError } from './types';
+import type { ShareContentRepository } from './types';
+
+export * from './types';
+export { ensureShareContentIndexes, SHARE_CONTENT_IDENTITY_INDEX } from './initialize';
+
+/**
+ * Bind the dedicated `share_content` collection from a caller-provided `Db`.
+ * Deliberately does not import the service `@mongo` singleton, so nothing here
+ * opens a connection at import time and tests can inject a real/memory database.
+ */
+export const getShareContentCollection = (db: Db): Collection<MongoShareContentDocument> =>
+    db.collection<MongoShareContentDocument>(SHARE_CONTENT_COLLECTION);
+
+/**
+ * Build the narrow exact-object share-content repository over an injected
+ * collection.
+ *
+ * Operational contract:
+ * - `initialize()` must be awaited at startup; it installs the unique
+ *   `(namespace, objectId)` index. Every operation throws
+ *   {@link ShareContentRepositoryNotInitializedError} until then, so an
+ *   un-indexed database can never serve a write.
+ * - This repository is **not** an authorization boundary. The route batch must
+ *   verify the C1 service context (namespace/op/shareId/contentVersion/
+ *   ownerProfileId/objectId/operationId/requestHash) first, then pass the exact
+ *   verified tuple. The repository only enforces the data-level binding and the
+ *   active/tombstone state machine.
+ */
+export const createShareContentRepository = (
+    collection: Collection<MongoShareContentDocument>
+): ShareContentRepository => {
+    let initialized = false;
+
+    const requireInitialized = (): Collection<MongoShareContentDocument> => {
+        if (!initialized) throw new ShareContentRepositoryNotInitializedError();
+
+        return collection;
+    };
+
+    return {
+        collection,
+        initialize: async () => {
+            await ensureShareContentIndexes(collection);
+            initialized = true;
+        },
+        put: async (input: ShareContentPutInput) => putShareContent(requireInitialized(), input),
+        getContent: async (binding: ShareContentObjectBinding) =>
+            getShareContentContent(requireInitialized(), binding),
+        getRecovery: async (binding: ShareContentObjectBinding) =>
+            getShareContentRecovery(requireInitialized(), binding),
+        stat: async (binding: ShareContentObjectBinding) =>
+            statShareContent(requireInitialized(), binding),
+        delete: async (binding: ShareContentObjectBinding) =>
+            deleteShareContent(requireInitialized(), binding),
+    };
+};

package/src/accesslayer/share-content/initialize.ts

@@ -0,0 +1,24 @@
+import type { Collection } from 'mongodb';
+
+import type { MongoShareContentDocument } from '@models';
+
+/** Stable index name so operators can verify/report the installed index. */
+export const SHARE_CONTENT_IDENTITY_INDEX = 'share_content_identity_unique';
+
+/**
+ * Explicitly install the required indexes before any operation is served.
+ *
+ * The unique `(namespace, objectId)` index is what makes create-only writes and
+ * permanent tombstones atomic: without it, a duplicate `insertOne` would create a
+ * second document instead of failing closed. Index creation is awaited by
+ * {@link createShareContentRepository}.initialize; it is never left to an
+ * eventual background build.
+ */
+export const ensureShareContentIndexes = async (
+    collection: Collection<MongoShareContentDocument>
+): Promise<void> => {
+    await collection.createIndex(
+        { namespace: 1, objectId: 1 },
+        { unique: true, name: SHARE_CONTENT_IDENTITY_INDEX }
+    );
+};

package/src/accesslayer/share-content/internal.ts

@@ -0,0 +1,89 @@
+import type { Filter } from 'mongodb';
+
+import {
+    ShareContentObjectBindingValidator,
+    type MongoShareContentActive,
+    type MongoShareContentDocument,
+    type MongoShareContentTombstone,
+    type ShareContentObjectBinding,
+} from '@models';
+
+import type { ShareContentActiveSummary, ShareContentTombstoneSummary } from './types';
+
+/**
+ * Bounded retry count for the atomic insert/delete race loops. The state machine
+ * is monotonic (active -> tombstone, never back), so the loop always settles; the
+ * bound protects against a pathological unique-index/driver anomaly rather than
+ * ordinary contention.
+ */
+export const MAX_SHARE_CONTENT_ATTEMPTS = 5;
+
+export const parseShareContentBinding = (raw: unknown): ShareContentObjectBinding | null => {
+    const parsed = ShareContentObjectBindingValidator.safeParse(raw);
+
+    return parsed.success ? parsed.data : null;
+};
+
+/** Exact six-field binding filter. Missing any field would widen the query. */
+export const shareContentBindingFilter = (
+    binding: ShareContentObjectBinding
+): Filter<MongoShareContentDocument> => ({
+    namespace: binding.namespace,
+    ownerProfileId: binding.ownerProfileId,
+    shareId: binding.shareId,
+    contentVersion: binding.contentVersion,
+    objectId: binding.objectId,
+    operationId: binding.operationId,
+});
+
+/** Identity filter for the unique `(namespace, objectId)` index. */
+export const shareContentIdentityFilter = (
+    binding: Pick<ShareContentObjectBinding, 'namespace' | 'objectId'>
+): Filter<MongoShareContentDocument> => ({
+    namespace: binding.namespace,
+    objectId: binding.objectId,
+});
+
+export const bindingMatchesDocument = (
+    doc: MongoShareContentDocument,
+    binding: ShareContentObjectBinding
+): boolean =>
+    doc.namespace === binding.namespace &&
+    doc.ownerProfileId === binding.ownerProfileId &&
+    doc.shareId === binding.shareId &&
+    doc.contentVersion === binding.contentVersion &&
+    doc.objectId === binding.objectId &&
+    doc.operationId === binding.operationId;
+
+/** MongoDB duplicate-key error (unique index violation). */
+export const isDuplicateKeyError = (error: unknown): boolean =>
+    typeof error === 'object' && error !== null && (error as { code?: unknown }).code === 11000;
+
+export const toActiveSummary = (doc: MongoShareContentActive): ShareContentActiveSummary => ({
+    kind: 'active',
+    namespace: doc.namespace,
+    ownerProfileId: doc.ownerProfileId,
+    shareId: doc.shareId,
+    contentVersion: doc.contentVersion,
+    objectId: doc.objectId,
+    operationId: doc.operationId,
+    contentHash: doc.contentHash,
+    payloadHash: doc.payloadHash,
+    ciphertextBytes: doc.ciphertextBytes,
+    recoveryBytes: doc.recoveryBytes,
+    createdAt: doc.createdAt,
+});
+
+export const toTombstoneSummary = (
+    doc: MongoShareContentTombstone
+): ShareContentTombstoneSummary => ({
+    kind: 'tombstone',
+    namespace: doc.namespace,
+    ownerProfileId: doc.ownerProfileId,
+    shareId: doc.shareId,
+    contentVersion: doc.contentVersion,
+    objectId: doc.objectId,
+    operationId: doc.operationId,
+    ...(doc.contentHash === undefined ? {} : { contentHash: doc.contentHash }),
+    deletedAt: doc.deletedAt,
+});

package/src/accesslayer/share-content/put.ts

@@ -0,0 +1,93 @@
+import type { Collection } from 'mongodb';
+
+import {
+    ShareContentPutInputValidator,
+    computeShareContentHash,
+    computeSharePayloadHash,
+    measureShareContentPayload,
+    type MongoShareContentActive,
+    type MongoShareContentDocument,
+    type ShareContentPutInput,
+} from '@models';
+
+import {
+    MAX_SHARE_CONTENT_ATTEMPTS,
+    bindingMatchesDocument,
+    isDuplicateKeyError,
+    shareContentIdentityFilter,
+    toActiveSummary,
+} from './internal';
+import type { ShareContentPutResult } from './types';
+
+const buildActiveDocument = (
+    input: ShareContentPutInput,
+    contentHash: string
+): MongoShareContentActive => {
+    const { ciphertextBytes, recoveryBytes } = measureShareContentPayload(input);
+
+    return {
+        kind: 'active',
+        namespace: input.namespace,
+        ownerProfileId: input.ownerProfileId,
+        shareId: input.shareId,
+        contentVersion: input.contentVersion,
+        objectId: input.objectId,
+        operationId: input.operationId,
+        contentHash,
+        payloadHash: computeSharePayloadHash(input),
+        envelope: input.envelope,
+        ownerEncryptedRecovery: input.ownerEncryptedRecovery,
+        ciphertextBytes,
+        recoveryBytes,
+        createdAt: new Date(),
+    };
+};
+
+/**
+ * Create-only immutable write.
+ *
+ * The write is an atomic `insertOne` against the unique `(namespace, objectId)`
+ * index; there is no read-then-write window. On a duplicate key the existing
+ * document is classified: a tombstone is permanent, an active document with the
+ * same derived hash and all six bindings is an exact idempotent success, and
+ * anything else is a conflict. Because active documents are never replaced and
+ * tombstones are permanent, the classification read cannot be invalidated by a
+ * concurrent writer in a way that resurrects content.
+ */
+export const putShareContent = async (
+    collection: Collection<MongoShareContentDocument>,
+    rawInput: unknown
+): Promise<ShareContentPutResult> => {
+    const parsed = ShareContentPutInputValidator.safeParse(rawInput);
+
+    if (!parsed.success) return { ok: false, error: 'INVALID_INPUT' };
+
+    const input = parsed.data;
+    const contentHash = computeShareContentHash(input);
+
+    for (let attempt = 0; attempt < MAX_SHARE_CONTENT_ATTEMPTS; attempt += 1) {
+        const document = buildActiveDocument(input, contentHash);
+
+        try {
+            await collection.insertOne(document);
+
+            return { ok: true, value: { status: 'created', record: toActiveSummary(document) } };
+        } catch (error) {
+            if (!isDuplicateKeyError(error)) return { ok: false, error: 'STORE_ERROR' };
+        }
+
+        const existing = await collection.findOne(shareContentIdentityFilter(input));
+
+        if (existing === null) continue;
+
+        if (existing.kind === 'tombstone') return { ok: false, error: 'TOMBSTONED' };
+
+        if (existing.contentHash === contentHash && bindingMatchesDocument(existing, input)) {
+            return { ok: true, value: { status: 'idempotent', record: toActiveSummary(existing) } };
+        }
+
+        return { ok: false, error: 'CONFLICT' };
+    }
+
+    return { ok: false, error: 'CONFLICT' };
+};

package/src/accesslayer/share-content/read.ts

@@ -0,0 +1,124 @@
+import type { Collection } from 'mongodb';
+
+import type { MongoShareContentDocument } from '@models';
+
+import {
+    parseShareContentBinding,
+    shareContentBindingFilter,
+    toActiveSummary,
+    toTombstoneSummary,
+} from './internal';
+import type {
+    ShareContentContentProjection,
+    ShareContentRecoveryProjection,
+    ShareContentRepositoryResult,
+    ShareContentStatProjection,
+} from './types';
+
+/**
+ * Content projection for the exact active object. The owner recovery is never
+ * read into this projection. A missing object, a tombstone or any binding
+ * mismatch is reported as the same opaque `NOT_FOUND`, so the repository does
+ * not disclose another owner's object existence.
+ */
+export const getShareContentContent = async (
+    collection: Collection<MongoShareContentDocument>,
+    rawBinding: unknown
+): Promise<ShareContentRepositoryResult<ShareContentContentProjection>> => {
+    const binding = parseShareContentBinding(rawBinding);
+
+    if (binding === null) return { ok: false, error: 'INVALID_INPUT' };
+
+    const document = await collection.findOne(
+        { ...shareContentBindingFilter(binding), kind: 'active' },
+        { projection: { ownerEncryptedRecovery: 0 } }
+    );
+
+    if (document === null || document.kind !== 'active') return { ok: false, error: 'NOT_FOUND' };
+
+    return {
+        ok: true,
+        value: {
+            kind: 'active',
+            namespace: binding.namespace,
+            ownerProfileId: binding.ownerProfileId,
+            shareId: binding.shareId,
+            contentVersion: binding.contentVersion,
+            objectId: binding.objectId,
+            operationId: binding.operationId,
+            contentHash: document.contentHash,
+            payloadHash: document.payloadHash,
+            envelope: document.envelope,
+            ciphertextBytes: document.ciphertextBytes,
+            createdAt: document.createdAt,
+        },
+    };
+};
+
+/**
+ * Owner-only recovery projection for the exact active object. The ciphertext
+ * envelope is never read into this projection and the returned value carries no
+ * content bytes. The route layer must call this only after verifying the owner
+ * context; the repository is not an authorization boundary.
+ */
+export const getShareContentRecovery = async (
+    collection: Collection<MongoShareContentDocument>,
+    rawBinding: unknown
+): Promise<ShareContentRepositoryResult<ShareContentRecoveryProjection>> => {
+    const binding = parseShareContentBinding(rawBinding);
+
+    if (binding === null) return { ok: false, error: 'INVALID_INPUT' };
+
+    const document = await collection.findOne(
+        { ...shareContentBindingFilter(binding), kind: 'active' },
+        { projection: { envelope: 0, ciphertextBytes: 0 } }
+    );
+
+    if (document === null || document.kind !== 'active') return { ok: false, error: 'NOT_FOUND' };
+
+    return {
+        ok: true,
+        value: {
+            kind: 'active',
+            namespace: binding.namespace,
+            ownerProfileId: binding.ownerProfileId,
+            shareId: binding.shareId,
+            contentVersion: binding.contentVersion,
+            objectId: binding.objectId,
+            operationId: binding.operationId,
+            contentHash: document.contentHash,
+            payloadHash: document.payloadHash,
+            ownerEncryptedRecovery: document.ownerEncryptedRecovery,
+            recoveryBytes: document.recoveryBytes,
+            createdAt: document.createdAt,
+        },
+    };
+};
+
+/**
+ * Existence/hash/byte summary for the exact tuple. Returns the tombstone summary
+ * for a matching permanent tombstone (reconciliation needs it) and the opaque
+ * `NOT_FOUND` for any binding mismatch. No ciphertext or recovery is read.
+ */
+export const statShareContent = async (
+    collection: Collection<MongoShareContentDocument>,
+    rawBinding: unknown
+): Promise<ShareContentRepositoryResult<ShareContentStatProjection>> => {
+    const binding = parseShareContentBinding(rawBinding);
+
+    if (binding === null) return { ok: false, error: 'INVALID_INPUT' };
+
+    const document = await collection.findOne(shareContentBindingFilter(binding), {
+        projection: { envelope: 0, ownerEncryptedRecovery: 0 },
+    });
+
+    if (document === null) return { ok: false, error: 'NOT_FOUND' };
+
+    return {
+        ok: true,
+        value:
+            document.kind === 'tombstone'
+                ? toTombstoneSummary(document)
+                : toActiveSummary(document),
+    };
+};

package/src/accesslayer/share-content/types.ts

@@ -0,0 +1,155 @@
+import type { Collection } from 'mongodb';
+
+import type {
+    MongoShareContentDocument,
+    ShareContentHash,
+    ShareContentObjectBinding,
+    ShareContentPutInput,
+    ShareEnvelope,
+    ShareOwnerRecovery,
+} from '@models';
+
+/**
+ * Stable, non-secret repository result codes. Routes map every failure to a
+ * single generic external rejection; a repository error must never be returned
+ * verbatim to a caller.
+ */
+export type ShareContentRepositoryError =
+    'INVALID_INPUT' | 'NOT_FOUND' | 'TOMBSTONED' | 'BINDING_MISMATCH' | 'CONFLICT' | 'STORE_ERROR';
+
+export type ShareContentRepositoryFailure = { ok: false; error: ShareContentRepositoryError };
+
+export type ShareContentRepositoryResult<T> =
+    { ok: true; value: T } | ShareContentRepositoryFailure;
+
+/** `created` for the first write, `idempotent` for an exact retry. */
+export type ShareContentWriteStatus = 'created' | 'idempotent';
+
+/** Non-sensitive active summary; never includes ciphertext or recovery. */
+export type ShareContentActiveSummary = {
+    kind: 'active';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash: ShareContentHash;
+    payloadHash: ShareContentHash;
+    ciphertextBytes: number;
+    recoveryBytes: number;
+    createdAt: Date;
+};
+
+/** Tombstone summary retained after deletion. */
+export type ShareContentTombstoneSummary = {
+    kind: 'tombstone';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash?: ShareContentHash;
+    deletedAt: Date;
+};
+
+/**
+ * Content projection. The owner recovery is deliberately absent: it is only
+ * reachable through the separately authorized {@link
+ * ShareContentRepository.getRecovery} method.
+ */
+export type ShareContentContentProjection = {
+    kind: 'active';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash: ShareContentHash;
+    payloadHash: ShareContentHash;
+    envelope: ShareEnvelope;
+    ciphertextBytes: number;
+    createdAt: Date;
+};
+
+/**
+ * Owner-only recovery projection. The ciphertext envelope is absent. The route
+ * layer must call this only for an authenticated owner-recovery request; the
+ * repository is not an authorization boundary by itself.
+ */
+export type ShareContentRecoveryProjection = {
+    kind: 'active';
+    namespace: string;
+    ownerProfileId: string;
+    shareId: string;
+    contentVersion: number;
+    objectId: string;
+    operationId: string;
+    contentHash: ShareContentHash;
+    payloadHash: ShareContentHash;
+    ownerEncryptedRecovery: ShareOwnerRecovery;
+    recoveryBytes: number;
+    createdAt: Date;
+};
+
+export type ShareContentStatProjection = ShareContentActiveSummary | ShareContentTombstoneSummary;
+
+/** Successful put value: `created` or an exact idempotent retry. */
+export type ShareContentPutResultValue = {
+    status: ShareContentWriteStatus;
+    record: ShareContentActiveSummary;
+};
+export type ShareContentPutResult = ShareContentRepositoryResult<ShareContentPutResultValue>;
+
+/**
+ * Narrow exact-object repository. There is deliberately no list, scan,
+ * wildcard or `deleteOwner` method: every call is bound to one immutable tuple.
+ *
+ * The repository enforces data-level bindings only. It is **not** an
+ * authorization boundary: callers must have already verified the C1 service
+ * authorization context (namespace/op/shareId/contentVersion/ownerProfileId/
+ * objectId/operationId/requestHash) before invoking it.
+ */
+export type ShareContentRepository = {
+    /** The injected collection. Useful for diagnostics; not a query surface. */
+    readonly collection: Collection<MongoShareContentDocument>;
+    /**
+     * Explicitly install the required unique identity index before serving any
+     * operation. Must be awaited during startup; index creation is never left to
+     * an eventual background build.
+     */
+    initialize: () => Promise<void>;
+    /** Create-only write. Same tuple + derived hash is an idempotent success. */
+    put: (input: ShareContentPutInput) => Promise<ShareContentPutResult>;
+    /** Content projection (no recovery) for the active object, or a failure. */
+    getContent: (
+        binding: ShareContentObjectBinding
+    ) => Promise<ShareContentRepositoryResult<ShareContentContentProjection>>;
+    /** Owner-only recovery projection for the active object, or a failure. */
+    getRecovery: (
+        binding: ShareContentObjectBinding
+    ) => Promise<ShareContentRepositoryResult<ShareContentRecoveryProjection>>;
+    /** Existence/hash/byte summary for the exact tuple (active or tombstone). */
+    stat: (
+        binding: ShareContentObjectBinding
+    ) => Promise<ShareContentRepositoryResult<ShareContentStatProjection>>;
+    /**
+     * Atomically tombstone the exact object. Deleting an absent identity writes a
+     * permanent tombstone first, so a late concurrent put can never resurrect it.
+     */
+    delete: (
+        binding: ShareContentObjectBinding
+    ) => Promise<ShareContentRepositoryResult<ShareContentTombstoneSummary>>;
+};
+
+/** Thrown when an operation is attempted before {@link ShareContentRepository.initialize}. */
+export class ShareContentRepositoryNotInitializedError extends Error {
+    readonly code = 'SHARE_CONTENT_REPOSITORY_NOT_INITIALIZED';
+
+    constructor() {
+        super('share-content repository must be initialized before serving operations');
+        this.name = 'ShareContentRepositoryNotInitializedError';
+    }
+}

package/src/config/applyDockerStageConfig.ts

@@ -0,0 +1,6 @@
+import { applyLearnCloudStageConfig } from './stageConfig';
+
+// Side-effect import: runs before @environment is evaluated so Docker/local processes
+// pick up checked-in per-stage config. Keyed on CONFIG_STAGE (Lambda uses LAMBDA_STAGE);
+// explicit non-empty env values from the developer's .env still win.
+applyLearnCloudStageConfig(process.env.CONFIG_STAGE);