@utilarium/overcontext 0.0.5 → 0.0.6-dev.20260218224640.3065466

package/README.md

@@ -126,6 +126,22 @@ const workPeople = await ctx.getAll('person', 'work');
 - **Hierarchical**: Multi-level discovery with override behavior
 - **Custom**: Implement your own
 
+### Custom Filenames
+
+Control how entity files are named on disk with a filename strategy:
+
+```typescript
+const ctx = await discoverOvercontext({
+  schemas: { person: PersonSchema },
+  filenameStrategy: (entity) => {
+    const slug = (entity as any).slug;
+    return slug ? `${entity.id.substring(0, 8)}-${slug}` : entity.id;
+  },
+});
+```
+
+This produces files like `d00acdc4-gerald-corson.yaml` instead of `d00acdc4-5678-9abc-def0-111111111111.yaml`. Lookups, existence checks, and deletes work transparently regardless of the filename on disk. See the [Storage Providers](./guide/storage-providers.md#custom-filename-strategy) guide for details.
+
 ## API Overview
 
 ### CRUD Operations

package/dist/discovery/hierarchical-provider.d.ts

@@ -1,10 +1,13 @@
 import { StorageProvider } from '../storage/interface';
+import { BaseEntity } from '../schema/base';
 import { SchemaRegistry } from '../schema/registry';
 import { ContextRoot } from './context-root';
 export interface HierarchicalProviderOptions {
     contextRoot: ContextRoot;
     registry: SchemaRegistry;
     readonly?: boolean;
+    /** Custom filename strategy passed through to filesystem providers */
+    filenameStrategy?: (entity: BaseEntity) => string;
 }
 /**
  * Storage provider that reads from multiple context directories

package/dist/discovery/hierarchical-provider.js

@@ -4,7 +4,7 @@ import { createFileSystemProvider } from '../storage/filesystem.js';
  * Storage provider that reads from multiple context directories
  * and writes to the primary (closest) directory.
  */ const createHierarchicalProvider = async (options)=>{
-    const { contextRoot, registry, readonly = false } = options;
+    const { contextRoot, registry, readonly = false, filenameStrategy } = options;
     if (contextRoot.contextPaths.length === 0) {
         throw new Error('No context directories found');
     }
@@ -15,7 +15,8 @@ import { createFileSystemProvider } from '../storage/filesystem.js';
             basePath: contextPath,
             registry,
             createIfMissing: false,
-            readonly: true
+            readonly: true,
+            filenameStrategy
         });
         await fsProvider.initialize();
         readProviders.push(fsProvider);
@@ -25,7 +26,8 @@ import { createFileSystemProvider } from '../storage/filesystem.js';
         basePath: contextRoot.primary,
         registry,
         createIfMissing: true,
-        readonly
+        readonly,
+        filenameStrategy
     });
     await primaryProvider.initialize();
     const findEntities = async (filter)=>{

package/dist/discovery/hierarchical-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"hierarchical-provider.js","sources":["../../src/discovery/hierarchical-provider.ts"],"sourcesContent":["import { StorageProvider, EntityFilter } from '../storage/interface';\nimport { BaseEntity } from '../schema/base';\nimport { SchemaRegistry } from '../schema/registry';\nimport { createFileSystemProvider } from '../storage/filesystem';\nimport { ContextRoot } from './context-root';\n\nexport interface HierarchicalProviderOptions {\n    contextRoot: ContextRoot;\n    registry: SchemaRegistry;\n    readonly?: boolean;\n}\n\n/**\n * Storage provider that reads from multiple context directories\n * and writes to the primary (closest) directory.\n */\nexport const createHierarchicalProvider = async (\n    options: HierarchicalProviderOptions\n): Promise<StorageProvider> => {\n    const { contextRoot, registry, readonly = false } = options;\n\n    if (contextRoot.contextPaths.length === 0) {\n        throw new Error('No context directories found');\n    }\n\n    // Create read-only providers for each context directory\n    const readProviders: StorageProvider[] = [];\n    for (const contextPath of contextRoot.contextPaths) {\n        const fsProvider = await createFileSystemProvider({\n            basePath: contextPath,\n            registry,\n            createIfMissing: false,\n            readonly: true,\n        });\n        await fsProvider.initialize();\n        readProviders.push(fsProvider);\n    }\n\n    // Primary provider for writes\n    const primaryProvider = await createFileSystemProvider({\n        basePath: contextRoot.primary!,\n        registry,\n        createIfMissing: true,\n        readonly,\n    });\n    await primaryProvider.initialize();\n\n    const findEntities = async <T extends BaseEntity>(filter: EntityFilter): Promise<T[]> => {\n        const byId = new Map<string, T>();\n\n        // Create a filter without pagination - we'll apply pagination after merging\n        // This prevents double-pagination (sub-providers paginating, then us paginating again)\n        const filterWithoutPagination: EntityFilter = {\n            type: filter.type,\n            namespace: filter.namespace,\n            ids: filter.ids,\n            search: filter.search,\n        };\n\n        for (const p of [...readProviders].reverse()) {\n            const results = await p.find<T>(filterWithoutPagination);\n            for (const entity of results) {\n                byId.set(entity.id, entity);\n            }\n        }\n\n        let results = Array.from(byId.values());\n\n        // Apply pagination once, after merging all results\n        if (filter.offset) results = results.slice(filter.offset);\n        if (filter.limit) results = results.slice(0, filter.limit);\n\n        return results;\n    };\n\n    return {\n        name: 'hierarchical',\n        location: contextRoot.primary!,\n        registry,\n\n        async initialize() { },\n\n        async dispose() {\n            for (const p of readProviders) await p.dispose();\n            await primaryProvider.dispose();\n        },\n\n        async isAvailable() {\n            return primaryProvider.isAvailable();\n        },\n\n        // Read operations search all providers (closest first)\n        async get<T extends BaseEntity>(type: string, id: string, namespace?: string) {\n            for (const p of readProviders) {\n                const entity = await p.get<T>(type, id, namespace);\n                if (entity) return entity;\n            }\n            return undefined;\n        },\n\n        async getAll<T extends BaseEntity>(type: string, namespace?: string) {\n            const byId = new Map<string, T>();\n\n            // Process in reverse order so closest overwrites\n            for (const p of [...readProviders].reverse()) {\n                const entities = await p.getAll<T>(type, namespace);\n                for (const entity of entities) {\n                    byId.set(entity.id, entity);\n                }\n            }\n\n            return Array.from(byId.values());\n        },\n\n        find: findEntities,\n\n        async exists(type: string, id: string, namespace?: string) {\n            for (const p of readProviders) {\n                if (await p.exists(type, id, namespace)) return true;\n            }\n            return false;\n        },\n\n        async count(filter: EntityFilter) {\n            const results = await findEntities(filter);\n            return results.length;\n        },\n\n        // Write operations go to primary\n        save: (entity, namespace) => primaryProvider.save(entity, namespace),\n        delete: (type, id, namespace) => primaryProvider.delete(type, id, namespace),\n        saveBatch: (entities, namespace) => primaryProvider.saveBatch(entities, namespace),\n        deleteBatch: (refs, namespace) => primaryProvider.deleteBatch(refs, namespace),\n\n        listNamespaces: () => Promise.resolve(contextRoot.allNamespaces),\n        namespaceExists: (ns) => Promise.resolve(contextRoot.allNamespaces.includes(ns)),\n        listTypes: () => Promise.resolve(contextRoot.allTypes),\n    };\n};\n"],"names":["createHierarchicalProvider","options","contextRoot","registry","readonly","contextPaths","length","Error","readProviders","contextPath","fsProvider","createFileSystemProvider","basePath","createIfMissing","initialize","push","primaryProvider","primary","findEntities","filter","byId","Map","filterWithoutPagination","type","namespace","ids","search","p","reverse","results","find","entity","set","id","Array","from","values","offset","slice","limit","name","location","dispose","isAvailable","get","undefined","getAll","entities","exists","count","save","delete","saveBatch","deleteBatch","refs","listNamespaces","Promise","resolve","allNamespaces","namespaceExists","ns","includes","listTypes","allTypes"],"mappings":"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"}
+{"version":3,"file":"hierarchical-provider.js","sources":["../../src/discovery/hierarchical-provider.ts"],"sourcesContent":["import { StorageProvider, EntityFilter } from '../storage/interface';\nimport { BaseEntity } from '../schema/base';\nimport { SchemaRegistry } from '../schema/registry';\nimport { createFileSystemProvider } from '../storage/filesystem';\nimport { ContextRoot } from './context-root';\n\nexport interface HierarchicalProviderOptions {\n    contextRoot: ContextRoot;\n    registry: SchemaRegistry;\n    readonly?: boolean;\n    /** Custom filename strategy passed through to filesystem providers */\n    filenameStrategy?: (entity: BaseEntity) => string;\n}\n\n/**\n * Storage provider that reads from multiple context directories\n * and writes to the primary (closest) directory.\n */\nexport const createHierarchicalProvider = async (\n    options: HierarchicalProviderOptions\n): Promise<StorageProvider> => {\n    const { contextRoot, registry, readonly = false, filenameStrategy } = options;\n\n    if (contextRoot.contextPaths.length === 0) {\n        throw new Error('No context directories found');\n    }\n\n    // Create read-only providers for each context directory\n    const readProviders: StorageProvider[] = [];\n    for (const contextPath of contextRoot.contextPaths) {\n        const fsProvider = await createFileSystemProvider({\n            basePath: contextPath,\n            registry,\n            createIfMissing: false,\n            readonly: true,\n            filenameStrategy,\n        });\n        await fsProvider.initialize();\n        readProviders.push(fsProvider);\n    }\n\n    // Primary provider for writes\n    const primaryProvider = await createFileSystemProvider({\n        basePath: contextRoot.primary!,\n        registry,\n        createIfMissing: true,\n        readonly,\n        filenameStrategy,\n    });\n    await primaryProvider.initialize();\n\n    const findEntities = async <T extends BaseEntity>(filter: EntityFilter): Promise<T[]> => {\n        const byId = new Map<string, T>();\n\n        // Create a filter without pagination - we'll apply pagination after merging\n        // This prevents double-pagination (sub-providers paginating, then us paginating again)\n        const filterWithoutPagination: EntityFilter = {\n            type: filter.type,\n            namespace: filter.namespace,\n            ids: filter.ids,\n            search: filter.search,\n        };\n\n        for (const p of [...readProviders].reverse()) {\n            const results = await p.find<T>(filterWithoutPagination);\n            for (const entity of results) {\n                byId.set(entity.id, entity);\n            }\n        }\n\n        let results = Array.from(byId.values());\n\n        // Apply pagination once, after merging all results\n        if (filter.offset) results = results.slice(filter.offset);\n        if (filter.limit) results = results.slice(0, filter.limit);\n\n        return results;\n    };\n\n    return {\n        name: 'hierarchical',\n        location: contextRoot.primary!,\n        registry,\n\n        async initialize() { },\n\n        async dispose() {\n            for (const p of readProviders) await p.dispose();\n            await primaryProvider.dispose();\n        },\n\n        async isAvailable() {\n            return primaryProvider.isAvailable();\n        },\n\n        // Read operations search all providers (closest first)\n        async get<T extends BaseEntity>(type: string, id: string, namespace?: string) {\n            for (const p of readProviders) {\n                const entity = await p.get<T>(type, id, namespace);\n                if (entity) return entity;\n            }\n            return undefined;\n        },\n\n        async getAll<T extends BaseEntity>(type: string, namespace?: string) {\n            const byId = new Map<string, T>();\n\n            // Process in reverse order so closest overwrites\n            for (const p of [...readProviders].reverse()) {\n                const entities = await p.getAll<T>(type, namespace);\n                for (const entity of entities) {\n                    byId.set(entity.id, entity);\n                }\n            }\n\n            return Array.from(byId.values());\n        },\n\n        find: findEntities,\n\n        async exists(type: string, id: string, namespace?: string) {\n            for (const p of readProviders) {\n                if (await p.exists(type, id, namespace)) return true;\n            }\n            return false;\n        },\n\n        async count(filter: EntityFilter) {\n            const results = await findEntities(filter);\n            return results.length;\n        },\n\n        // Write operations go to primary\n        save: (entity, namespace) => primaryProvider.save(entity, namespace),\n        delete: (type, id, namespace) => primaryProvider.delete(type, id, namespace),\n        saveBatch: (entities, namespace) => primaryProvider.saveBatch(entities, namespace),\n        deleteBatch: (refs, namespace) => primaryProvider.deleteBatch(refs, namespace),\n\n        listNamespaces: () => Promise.resolve(contextRoot.allNamespaces),\n        namespaceExists: (ns) => Promise.resolve(contextRoot.allNamespaces.includes(ns)),\n        listTypes: () => Promise.resolve(contextRoot.allTypes),\n    };\n};\n"],"names":["createHierarchicalProvider","options","contextRoot","registry","readonly","filenameStrategy","contextPaths","length","Error","readProviders","contextPath","fsProvider","createFileSystemProvider","basePath","createIfMissing","initialize","push","primaryProvider","primary","findEntities","filter","byId","Map","filterWithoutPagination","type","namespace","ids","search","p","reverse","results","find","entity","set","id","Array","from","values","offset","slice","limit","name","location","dispose","isAvailable","get","undefined","getAll","entities","exists","count","save","delete","saveBatch","deleteBatch","refs","listNamespaces","Promise","resolve","allNamespaces","namespaceExists","ns","includes","listTypes","allTypes"],"mappings":"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"}

package/dist/discovery/index.d.ts

@@ -1,4 +1,5 @@
 import { SchemaMap } from '../schema/registry';
+import { BaseEntity } from '../schema/base';
 import { ContextRootOptions } from './context-root';
 import { OvercontextAPI } from '../api/context';
 export * from './walker';
@@ -11,6 +12,12 @@ export interface DiscoverOptions<TSchemas extends SchemaMap> extends ContextRoot
     pluralNames?: Partial<Record<keyof TSchemas, string>>;
     /** Whether context is readonly */
     readonly?: boolean;
+    /**
+     * Custom filename strategy for entity files.
+     * Given an entity, returns the filename stem (without extension).
+     * When not provided, entity.id is used as the filename.
+     */
+    filenameStrategy?: (entity: BaseEntity) => string;
 }
 /**
  * Discover context directories and create an API.

package/dist/discovery/index.js

@@ -10,7 +10,7 @@ import { createContext } from '../api/context.js';
 /**
  * Discover context directories and create an API.
  */ const discoverOvercontext = async (options)=>{
-    const { schemas, pluralNames = {}, readonly, ...rootOptions } = options;
+    const { schemas, pluralNames = {}, readonly, filenameStrategy, ...rootOptions } = options;
     // Create registry
     const registry = createSchemaRegistry();
     for (const [type, schema] of Object.entries(schemas)){
@@ -32,7 +32,8 @@ import { createContext } from '../api/context.js';
     const provider = await createHierarchicalProvider({
         contextRoot,
         registry,
-        readonly
+        readonly,
+        filenameStrategy
     });
     // Create context API
     return createContext({

package/dist/discovery/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../src/discovery/index.ts"],"sourcesContent":["export * from './walker';\nexport * from './context-root';\nexport * from './hierarchical-provider';\n\nimport { z } from 'zod';\nimport { SchemaMap, createSchemaRegistry } from '../schema/registry';\nimport { BaseEntity } from '../schema/base';\nimport { discoverContextRoot, ContextRootOptions } from './context-root';\nimport { createHierarchicalProvider } from './hierarchical-provider';\nimport { createContext, OvercontextAPI } from '../api/context';\n\nexport interface DiscoverOptions<TSchemas extends SchemaMap> extends ContextRootOptions {\n    /** Schemas to register */\n    schemas: TSchemas;\n\n    /** Custom plural names for types */\n    pluralNames?: Partial<Record<keyof TSchemas, string>>;\n\n    /** Whether context is readonly */\n    readonly?: boolean;\n}\n\n/**\n * Discover context directories and create an API.\n */\nexport const discoverOvercontext = async <TSchemas extends SchemaMap>(\n    options: DiscoverOptions<TSchemas>\n): Promise<OvercontextAPI<TSchemas>> => {\n    const { schemas, pluralNames = {}, readonly, ...rootOptions } = options;\n\n    // Create registry\n    const registry = createSchemaRegistry();\n    for (const [type, schema] of Object.entries(schemas)) {\n        registry.register({\n            type,\n            schema: schema as z.ZodType<BaseEntity>,\n            pluralName: (pluralNames as Record<string, string>)[type],\n        });\n    }\n\n    // Discover context directories\n    const contextRoot = await discoverContextRoot({\n        ...rootOptions,\n        registry,\n    });\n\n    if (!contextRoot.primary) {\n        throw new Error('No context directory found');\n    }\n\n    // Create hierarchical provider\n    const provider = await createHierarchicalProvider({\n        contextRoot,\n        registry,\n        readonly,\n    });\n\n    // Create context API\n    return createContext({\n        provider,\n        registry,\n        schemas,\n        defaultNamespace: undefined,\n    });\n};\n"],"names":["discoverOvercontext","options","schemas","pluralNames","readonly","rootOptions","registry","createSchemaRegistry","type","schema","Object","entries","register","pluralName","contextRoot","discoverContextRoot","primary","Error","provider","createHierarchicalProvider","createContext","defaultNamespace","undefined"],"mappings":";;;;;;;;;AAsBA;;IAGO,MAAMA,mBAAAA,GAAsB,OAC/BC,OAAAA,GAAAA;IAEA,MAAM,EAAEC,OAAO,EAAEC,WAAAA,GAAc,EAAE,EAAEC,QAAQ,EAAE,GAAGC,WAAAA,EAAa,GAAGJ,OAAAA;;AAGhE,IAAA,MAAMK,QAAAA,GAAWC,oBAAAA,EAAAA;IACjB,KAAK,MAAM,CAACC,IAAAA,EAAMC,MAAAA,CAAO,IAAIC,MAAAA,CAAOC,OAAO,CAACT,OAAAA,CAAAA,CAAU;AAClDI,QAAAA,QAAAA,CAASM,QAAQ,CAAC;AACdJ,YAAAA,IAAAA;YACAC,MAAAA,EAAQA,MAAAA;YACRI,UAAAA,EAAaV,WAAsC,CAACK,IAAAA;AACxD,SAAA,CAAA;AACJ,IAAA;;IAGA,MAAMM,WAAAA,GAAc,MAAMC,mBAAAA,CAAoB;AAC1C,QAAA,GAAGV,WAAW;AACdC,QAAAA;AACJ,KAAA,CAAA;IAEA,IAAI,CAACQ,WAAAA,CAAYE,OAAO,EAAE;AACtB,QAAA,MAAM,IAAIC,KAAAA,CAAM,4BAAA,CAAA;AACpB,IAAA;;IAGA,MAAMC,QAAAA,GAAW,MAAMC,0BAAAA,CAA2B;AAC9CL,QAAAA,WAAAA;AACAR,QAAAA,QAAAA;AACAF,QAAAA;AACJ,KAAA,CAAA;;AAGA,IAAA,OAAOgB,aAAAA,CAAc;AACjBF,QAAAA,QAAAA;AACAZ,QAAAA,QAAAA;AACAJ,QAAAA,OAAAA;QACAmB,gBAAAA,EAAkBC;AACtB,KAAA,CAAA;AACJ;;;;"}
+{"version":3,"file":"index.js","sources":["../../src/discovery/index.ts"],"sourcesContent":["export * from './walker';\nexport * from './context-root';\nexport * from './hierarchical-provider';\n\nimport { z } from 'zod';\nimport { SchemaMap, createSchemaRegistry } from '../schema/registry';\nimport { BaseEntity } from '../schema/base';\nimport { discoverContextRoot, ContextRootOptions } from './context-root';\nimport { createHierarchicalProvider } from './hierarchical-provider';\nimport { createContext, OvercontextAPI } from '../api/context';\n\nexport interface DiscoverOptions<TSchemas extends SchemaMap> extends ContextRootOptions {\n    /** Schemas to register */\n    schemas: TSchemas;\n\n    /** Custom plural names for types */\n    pluralNames?: Partial<Record<keyof TSchemas, string>>;\n\n    /** Whether context is readonly */\n    readonly?: boolean;\n\n    /**\n     * Custom filename strategy for entity files.\n     * Given an entity, returns the filename stem (without extension).\n     * When not provided, entity.id is used as the filename.\n     */\n    filenameStrategy?: (entity: BaseEntity) => string;\n}\n\n/**\n * Discover context directories and create an API.\n */\nexport const discoverOvercontext = async <TSchemas extends SchemaMap>(\n    options: DiscoverOptions<TSchemas>\n): Promise<OvercontextAPI<TSchemas>> => {\n    const { schemas, pluralNames = {}, readonly, filenameStrategy, ...rootOptions } = options;\n\n    // Create registry\n    const registry = createSchemaRegistry();\n    for (const [type, schema] of Object.entries(schemas)) {\n        registry.register({\n            type,\n            schema: schema as z.ZodType<BaseEntity>,\n            pluralName: (pluralNames as Record<string, string>)[type],\n        });\n    }\n\n    // Discover context directories\n    const contextRoot = await discoverContextRoot({\n        ...rootOptions,\n        registry,\n    });\n\n    if (!contextRoot.primary) {\n        throw new Error('No context directory found');\n    }\n\n    // Create hierarchical provider\n    const provider = await createHierarchicalProvider({\n        contextRoot,\n        registry,\n        readonly,\n        filenameStrategy,\n    });\n\n    // Create context API\n    return createContext({\n        provider,\n        registry,\n        schemas,\n        defaultNamespace: undefined,\n    });\n};\n"],"names":["discoverOvercontext","options","schemas","pluralNames","readonly","filenameStrategy","rootOptions","registry","createSchemaRegistry","type","schema","Object","entries","register","pluralName","contextRoot","discoverContextRoot","primary","Error","provider","createHierarchicalProvider","createContext","defaultNamespace","undefined"],"mappings":";;;;;;;;;AA6BA;;IAGO,MAAMA,mBAAAA,GAAsB,OAC/BC,OAAAA,GAAAA;AAEA,IAAA,MAAM,EAAEC,OAAO,EAAEC,WAAAA,GAAc,EAAE,EAAEC,QAAQ,EAAEC,gBAAgB,EAAE,GAAGC,aAAa,GAAGL,OAAAA;;AAGlF,IAAA,MAAMM,QAAAA,GAAWC,oBAAAA,EAAAA;IACjB,KAAK,MAAM,CAACC,IAAAA,EAAMC,MAAAA,CAAO,IAAIC,MAAAA,CAAOC,OAAO,CAACV,OAAAA,CAAAA,CAAU;AAClDK,QAAAA,QAAAA,CAASM,QAAQ,CAAC;AACdJ,YAAAA,IAAAA;YACAC,MAAAA,EAAQA,MAAAA;YACRI,UAAAA,EAAaX,WAAsC,CAACM,IAAAA;AACxD,SAAA,CAAA;AACJ,IAAA;;IAGA,MAAMM,WAAAA,GAAc,MAAMC,mBAAAA,CAAoB;AAC1C,QAAA,GAAGV,WAAW;AACdC,QAAAA;AACJ,KAAA,CAAA;IAEA,IAAI,CAACQ,WAAAA,CAAYE,OAAO,EAAE;AACtB,QAAA,MAAM,IAAIC,KAAAA,CAAM,4BAAA,CAAA;AACpB,IAAA;;IAGA,MAAMC,QAAAA,GAAW,MAAMC,0BAAAA,CAA2B;AAC9CL,QAAAA,WAAAA;AACAR,QAAAA,QAAAA;AACAH,QAAAA,QAAAA;AACAC,QAAAA;AACJ,KAAA,CAAA;;AAGA,IAAA,OAAOgB,aAAAA,CAAc;AACjBF,QAAAA,QAAAA;AACAZ,QAAAA,QAAAA;AACAL,QAAAA,OAAAA;QACAoB,gBAAAA,EAAkBC;AACtB,KAAA,CAAA;AACJ;;;;"}

package/dist/index.cjs

@@ -412,7 +412,7 @@ class NamespaceNotFoundError extends StorageError {
 };
 
 const createFileSystemProvider = async (options)=>{
-    const { basePath, registry, createIfMissing = true, extension = '.yaml', readonly = false, defaultNamespace } = options;
+    const { basePath, registry, createIfMissing = true, extension = '.yaml', readonly = false, defaultNamespace, filenameStrategy } = options;
     // --- Helper Functions ---
     /**
      * Sanitize a path component to prevent directory traversal attacks.
@@ -487,6 +487,53 @@ const createFileSystemProvider = async (options)=>{
         verifyPathWithinBase(fullPath);
         return fullPath;
     };
+    const getEntityPathForWrite = (entity, namespace)=>{
+        if (!filenameStrategy) {
+            return getEntityPath(entity.type, entity.id, namespace);
+        }
+        const filename = filenameStrategy(entity);
+        const safeFilename = sanitizePathComponent(filename, 'filename');
+        const dir = getEntityDir(entity.type, namespace);
+        const fullPath = path__namespace.join(dir, `${safeFilename}${extension}`);
+        verifyPathWithinBase(fullPath);
+        return fullPath;
+    };
+    /**
+     * Find the actual file path for an entity by id, handling custom filename strategies.
+     * Tries direct {id}{ext} first, then scans the directory using id prefix matching.
+     */ const findEntityFileById = async (type, id, namespace)=>{
+        const directPath = getEntityPath(type, id, namespace);
+        if (node_fs.existsSync(directPath)) {
+            return directPath;
+        }
+        if (!filenameStrategy) {
+            return undefined;
+        }
+        let dir;
+        try {
+            dir = getEntityDir(type, namespace);
+        } catch  {
+            return undefined;
+        }
+        if (!node_fs.existsSync(dir)) {
+            return undefined;
+        }
+        const prefix = id.substring(0, Math.min(8, id.length));
+        const files = await fs__namespace.readdir(dir);
+        const candidates = files.filter((f)=>(f.endsWith('.yaml') || f.endsWith('.yml')) && f.startsWith(prefix));
+        if (candidates.length === 1) {
+            return path__namespace.join(dir, candidates[0]);
+        }
+        // Multiple prefix matches — read and verify the id field
+        for (const file of candidates){
+            const filePath = path__namespace.join(dir, file);
+            const entity = await readEntity(filePath, type);
+            if (entity && entity.id === id) {
+                return filePath;
+            }
+        }
+        return undefined;
+    };
     const ensureDir = async (dir)=>{
         if (!node_fs.existsSync(dir) && createIfMissing && !readonly) {
             await fs__namespace.mkdir(dir, {
@@ -545,7 +592,16 @@ const createFileSystemProvider = async (options)=>{
         }
         const dir = getEntityDir(entity.type, namespace);
         await ensureDir(dir);
-        const filePath = getEntityPath(entity.type, entity.id, namespace);
+        const filePath = getEntityPathForWrite(entity, namespace);
+        // If filenameStrategy is set, clean up any old file with a different name for the same id
+        if (filenameStrategy) {
+            const oldPath = await findEntityFileById(entity.type, entity.id, namespace);
+            if (oldPath && path__namespace.resolve(oldPath) !== path__namespace.resolve(filePath)) {
+                try {
+                    await fs__namespace.unlink(oldPath);
+                } catch  {}
+            }
+        }
         // Remove framework-managed fields from saved YAML
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         const { type: _type, source: _source, ...entityToSave } = entity;
@@ -613,6 +669,11 @@ const createFileSystemProvider = async (options)=>{
         },
         async get (type, id, namespace) {
             const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
+            if (filenameStrategy) {
+                const filePath = await findEntityFileById(type, id, ns);
+                if (!filePath) return undefined;
+                return readEntity(filePath, type);
+            }
             const filePath = getEntityPath(type, id, ns);
             return readEntity(filePath, type);
         },
@@ -676,6 +737,10 @@ const createFileSystemProvider = async (options)=>{
         async exists (type, id, namespace) {
             const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
             try {
+                if (filenameStrategy) {
+                    const filePath = await findEntityFileById(type, id, ns);
+                    return filePath !== undefined;
+                }
                 const filePath = getEntityPath(type, id, ns);
                 return node_fs.existsSync(filePath);
             } catch  {
@@ -696,6 +761,12 @@ const createFileSystemProvider = async (options)=>{
             }
             const ns = namespace !== null && namespace !== void 0 ? namespace : defaultNamespace;
             try {
+                if (filenameStrategy) {
+                    const filePath = await findEntityFileById(type, id, ns);
+                    if (!filePath) return false;
+                    await fs__namespace.unlink(filePath);
+                    return true;
+                }
                 const filePath = getEntityPath(type, id, ns);
                 await fs__namespace.unlink(filePath);
                 return true;
@@ -1595,7 +1666,7 @@ const discoverContextRoot = async (options = {})=>{
  * Storage provider that reads from multiple context directories
  * and writes to the primary (closest) directory.
  */ const createHierarchicalProvider = async (options)=>{
-    const { contextRoot, registry, readonly = false } = options;
+    const { contextRoot, registry, readonly = false, filenameStrategy } = options;
     if (contextRoot.contextPaths.length === 0) {
         throw new Error('No context directories found');
     }
@@ -1606,7 +1677,8 @@ const discoverContextRoot = async (options = {})=>{
             basePath: contextPath,
             registry,
             createIfMissing: false,
-            readonly: true
+            readonly: true,
+            filenameStrategy
         });
         await fsProvider.initialize();
         readProviders.push(fsProvider);
@@ -1616,7 +1688,8 @@ const discoverContextRoot = async (options = {})=>{
         basePath: contextRoot.primary,
         registry,
         createIfMissing: true,
-        readonly
+        readonly,
+        filenameStrategy
     });
     await primaryProvider.initialize();
     const findEntities = async (filter)=>{
@@ -1701,7 +1774,7 @@ const discoverContextRoot = async (options = {})=>{
 /**
  * Discover context directories and create an API.
  */ const discoverOvercontext = async (options)=>{
-    const { schemas, pluralNames = {}, readonly, ...rootOptions } = options;
+    const { schemas, pluralNames = {}, readonly, filenameStrategy, ...rootOptions } = options;
     // Create registry
     const registry = createSchemaRegistry();
     for (const [type, schema] of Object.entries(schemas)){
@@ -1723,7 +1796,8 @@ const discoverContextRoot = async (options = {})=>{
     const provider = await createHierarchicalProvider({
         contextRoot,
         registry,
-        readonly
+        readonly,
+        filenameStrategy
     });
     // Create context API
     return createContext({