Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(gfs): expose updatedAt on GFS read and listing APIs

Alfredo Lopezc7c47b4fb6d7
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 5d430cb4d..62ec1ae47 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.524",
+ "version": "0.1.525",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.524",
+ "version": "0.1.525",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/image-policy": "file:../packages/image-policy",
diff --git a/control-api/package.json b/control-api/package.json
index fa90332bd..0d1304ce4 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.524",
+ "version": "0.1.525",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/gfs/resolve.ts b/control-api/src/gfs/resolve.ts
index f92aac7eb..5581c6a54 100644
--- a/control-api/src/gfs/resolve.ts
+++ b/control-api/src/gfs/resolve.ts
@@ -66,6 +66,7 @@ export interface ResolvedResource {
name: string
kind: string
pathCache: string | null
+ updatedAt: string
}
export interface ResolveStore {
@@ -98,7 +99,16 @@ export interface ResolveDb {
query(text: string, values?: unknown[]): Promise<{ rows: unknown[] }>
}
-const SELECT_COLS = 'resource_id, drive, name, kind, path_cache'
+const SELECT_COLS = 'resource_id, drive, name, kind, path_cache, updated_at'
+
+function toIsoTimestamp(value: unknown): string {
+ if (value instanceof Date) return value.toISOString()
+ if (typeof value === 'string' && value.length > 0) {
+ const parsed = new Date(value)
+ return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString()
+ }
+ throw new Error('gfs_resources.updated_at is required')
+}
function rowToResource(row: unknown): ResolvedResource {
const r = row as {
@@ -107,6 +117,7 @@ function rowToResource(row: unknown): ResolvedResource {
name: unknown
kind: unknown
path_cache: unknown
+ updated_at: unknown
}
return {
resourceId: String(r.resource_id),
@@ -114,6 +125,7 @@ function rowToResource(row: unknown): ResolvedResource {
name: String(r.name),
kind: String(r.kind),
pathCache: r.path_cache == null ? null : String(r.path_cache),
+ updatedAt: toIsoTimestamp(r.updated_at),
}
}
diff --git a/control-api/src/gfs/tree.ts b/control-api/src/gfs/tree.ts
index 143848482..7ba1a9c06 100644
--- a/control-api/src/gfs/tree.ts
+++ b/control-api/src/gfs/tree.ts
@@ -51,6 +51,7 @@ export interface ChildRow {
pathCache: string | null
bytes: number
version: number
+ updatedAt: string
}
export interface ChildView {
@@ -62,6 +63,16 @@ export interface ChildView {
path: string | null
bytes: number
version: number
+ updatedAt: string
+}
+
+function toIsoTimestamp(value: unknown): string {
+ if (value instanceof Date) return value.toISOString()
+ if (typeof value === 'string' && value.length > 0) {
+ const parsed = new Date(value)
+ return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString()
+ }
+ throw new Error('gfs_resources.updated_at is required')
}
export function toChildView(drive: string, row: ChildRow): ChildView {
@@ -75,6 +86,7 @@ export function toChildView(drive: string, row: ChildRow): ChildView {
path: row.pathCache,
bytes: row.bytes,
version: row.version,
+ updatedAt: row.updatedAt,
}
}
@@ -123,7 +135,7 @@ export class DbChildrenStore implements ChildrenStore {
// page) the cursor predicate is a no-op; otherwise it skips everything up to
// and including the cursor row.
const result = await this.db.query(
- `SELECT resource_id, name, kind, path_cache, bytes, version
+ `SELECT resource_id, name, kind, path_cache, bytes, version, updated_at
FROM gfs_resources
WHERE drive = $1 AND parent_resource_id = $2::uuid AND deleted_at IS NULL
AND ($3::text IS NULL OR (name, resource_id) > ($3, $4::uuid))
@@ -139,6 +151,7 @@ export class DbChildrenStore implements ChildrenStore {
path_cache: unknown
bytes: unknown
version: unknown
+ updated_at: unknown
}
return {
resourceId: String(r.resource_id),
@@ -147,6 +160,7 @@ export class DbChildrenStore implements ChildrenStore {
pathCache: r.path_cache == null ? null : String(r.path_cache),
bytes: Number(r.bytes ?? 0),
version: Number(r.version ?? 0),
+ updatedAt: toIsoTimestamp(r.updated_at),
}
})
}
diff --git a/control-api/src/routes/external/gfs.ts b/control-api/src/routes/external/gfs.ts
index 1cb0de8b4..9e6f33cab 100644
--- a/control-api/src/routes/external/gfs.ts
+++ b/control-api/src/routes/external/gfs.ts
@@ -179,6 +179,15 @@ function ridOf(resourceId: string): string {
return resourceId.replace(/-/g, '').toLowerCase()
}
+function toIsoTimestamp(value: unknown): string {
+ if (value instanceof Date) return value.toISOString()
+ if (typeof value === 'string' && value.length > 0) {
+ const parsed = new Date(value)
+ return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString()
+ }
+ throw new Error('gfs_resources.updated_at is required')
+}
+
function subjectColumns(subjects: Set<string>): { types: string[]; ids: string[] } {
const types: string[] = []
const ids: string[] = []
@@ -836,6 +845,7 @@ export function createExternalGfsRouter(): Router {
r.path_cache,
r.version,
r.bytes,
+ r.updated_at,
array_remove(array_agg(DISTINCT a.source), NULL) AS sources,
array_remove(array_agg(DISTINCT p.permission), NULL) AS permissions,
bool_or(a.covers_descendants) AS covers_descendants
@@ -844,7 +854,7 @@ export function createExternalGfsRouter(): Router {
ON r.drive = $1 AND r.resource_id = a.resource_id AND r.deleted_at IS NULL
LEFT JOIN LATERAL unnest(a.permissions) AS p(permission) ON true
WHERE ($4::text IS NULL OR (r.name, r.resource_id) > ($4, $5::uuid))
- GROUP BY r.resource_id, r.drive, r.parent_resource_id, r.name, r.kind, r.path_cache, r.version, r.bytes
+ GROUP BY r.resource_id, r.drive, r.parent_resource_id, r.name, r.kind, r.path_cache, r.version, r.bytes, r.updated_at
ORDER BY r.name, r.resource_id
LIMIT $6`,
[drive, types, ids, after?.n ?? null, after?.i ?? null, limit + 1]
@@ -858,6 +868,7 @@ export function createExternalGfsRouter(): Router {
path_cache: string | null
version: number
bytes: number
+ updated_at: unknown
sources: string[]
permissions: string[]
covers_descendants: boolean
@@ -880,6 +891,7 @@ export function createExternalGfsRouter(): Router {
path: row.path_cache,
version: Number(row.version ?? 0),
bytes: Number(row.bytes ?? 0),
+ updatedAt: toIsoTimestamp(row.updated_at),
sources: row.sources ?? [],
permissions: row.permissions ?? [],
coversDescendants: Boolean(row.covers_descendants),
diff --git a/control-api/src/routes/gfs/resolve.ts b/control-api/src/routes/gfs/resolve.ts
index be417115d..eb7a44a2d 100644
--- a/control-api/src/routes/gfs/resolve.ts
+++ b/control-api/src/routes/gfs/resolve.ts
@@ -19,6 +19,7 @@ export interface GfsResourceView {
name: string
kind: string
path: string | null
+ updatedAt: string
}
export function toResolveView(resource: ResolvedResource): GfsResourceView {
@@ -31,6 +32,7 @@ export function toResolveView(resource: ResolvedResource): GfsResourceView {
name: resource.name,
kind: resource.kind,
path: resource.pathCache,
+ updatedAt: resource.updatedAt,
}
}
diff --git a/control-api/test/gfs.resolve.test.ts b/control-api/test/gfs.resolve.test.ts
index 130c1caf2..fb2951b64 100644
--- a/control-api/test/gfs.resolve.test.ts
+++ b/control-api/test/gfs.resolve.test.ts
@@ -41,7 +41,14 @@ describe('parseGfsUri', () => {
})
function res(partial: Partial<ResolvedResource> & { resourceId: string }): ResolvedResource {
- return { drive: 'main', name: 'n', kind: 'directory', pathCache: null, ...partial }
+ return {
+ drive: 'main',
+ name: 'n',
+ kind: 'directory',
+ pathCache: null,
+ updatedAt: '2026-01-01T00:00:00.000Z',
+ ...partial,
+ }
}
class FakeStore implements ResolveStore {
@@ -107,6 +114,7 @@ const row = (resourceId: string, name = 'n', kind = 'directory') => ({
name,
kind,
path_cache: null,
+ updated_at: new Date('2026-01-01T00:00:00.000Z'),
})
describe('DbResolveStore', () => {
@@ -115,8 +123,10 @@ describe('DbResolveStore', () => {
db.responses = [{ rows: [row('r1')] }]
const out = await new DbResolveStore(db).getByRid('main', RID)
expect(out?.resourceId).toBe('r1')
+ expect(out?.updatedAt).toBe('2026-01-01T00:00:00.000Z')
expect(db.queries[0].text).toContain('resource_id = $2::uuid')
expect(db.queries[0].text).toContain('deleted_at IS NULL')
+ expect(db.queries[0].text).toContain('updated_at')
})
it('getByRid returns null when there is no live row', async () => {
diff --git a/control-api/test/gfs.resolveRoutes.test.ts b/control-api/test/gfs.resolveRoutes.test.ts
index 7866f37d9..4377afdb5 100644
--- a/control-api/test/gfs.resolveRoutes.test.ts
+++ b/control-api/test/gfs.resolveRoutes.test.ts
@@ -6,7 +6,14 @@ const RID = '8f3c2e1a4b5d4c6a9e7f1a2b3c4d5e6f'
const UUID = '8f3c2e1a-4b5d-4c6a-9e7f-1a2b3c4d5e6f'
function res(partial: Partial<ResolvedResource> & { resourceId: string }): ResolvedResource {
- return { drive: 'main', name: 'n', kind: 'directory', pathCache: null, ...partial }
+ return {
+ drive: 'main',
+ name: 'n',
+ kind: 'directory',
+ pathCache: null,
+ updatedAt: '2026-01-01T00:00:00.000Z',
+ ...partial,
+ }
}
class FakeStore implements ResolveStore {
@@ -26,6 +33,8 @@ describe('toResolveView', () => {
expect(view.rid).toBe(RID)
expect(view.gfsUri).toBe(`gfs://main/${RID}`)
expect(view.path).toBe('/org')
+ expect(view.updatedAt).toBe('2026-01-01T00:00:00.000Z')
+ expect(view.updatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T.*Z$/)
})
})
@@ -51,7 +60,11 @@ describe('resolveUriToHttp', () => {
store.byRid.set(RID, res({ resourceId: UUID, drive: 'main', name: 'org', pathCache: '/org' }))
const out = await resolveUriToHttp(store, `gfs://main/${RID}`)
expect(out.status).toBe(200)
- expect(out.body).toMatchObject({ gfsUri: `gfs://main/${RID}`, path: '/org' })
+ expect(out.body).toMatchObject({
+ gfsUri: `gfs://main/${RID}`,
+ path: '/org',
+ updatedAt: '2026-01-01T00:00:00.000Z',
+ })
})
})
diff --git a/control-api/test/gfs.tree.test.ts b/control-api/test/gfs.tree.test.ts
index 36f7b4cb5..02f2483f1 100644
--- a/control-api/test/gfs.tree.test.ts
+++ b/control-api/test/gfs.tree.test.ts
@@ -23,6 +23,7 @@ function child(name: string, n: number): ChildRow {
pathCache: `/${name}`,
bytes: 0,
version: 0,
+ updatedAt: '2026-01-01T00:00:00.000Z',
}
}
@@ -85,4 +86,15 @@ describe('listChildrenPaged', () => {
expect(view.gfsUri).toBe(`gfs://main/${rid(5)}`)
expect(view.path).toBe('/org')
})
+
+ it('child view exposes updatedAt as an ISO 8601 UTC string', () => {
+ const view = toChildView('main', child('org', 5))
+ expect(view.updatedAt).toBe('2026-01-01T00:00:00.000Z')
+ expect(view.updatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T.*Z$/)
+ })
+
+ it('does not encode updatedAt into the pagination cursor', () => {
+ expect(decodeCursor(encodeCursor('org', rid(5)))).toEqual({ n: 'org', i: rid(5) })
+ expect(JSON.stringify(decodeCursor(encodeCursor('org', rid(5))))).not.toContain('updatedAt')
+ })
})
diff --git a/control-api/test/gfsStructuralIntegrity.realPostgres.integration.test.ts b/control-api/test/gfsStructuralIntegrity.realPostgres.integration.test.ts
index 8b09d1728..f3eb83983 100644
--- a/control-api/test/gfsStructuralIntegrity.realPostgres.integration.test.ts
+++ b/control-api/test/gfsStructuralIntegrity.realPostgres.integration.test.ts
@@ -381,4 +381,57 @@ describeRealPostgres('GFS Phase 0 real PostgreSQL integrity', () => {
for (const client of [publisher, cleanup]) client.release()
}
}, 20_000)
+
+ it('advances updatedAt after replace and move without changing an untouched parent', async () => {
+ const tree = await seedTree(pool, 'updated-at')
+ const seed = '2000-01-01T00:00:00.000Z'
+ await pool.query(
+ `UPDATE gfs_resources SET created_at = $2::timestamptz, updated_at = $2::timestamptz WHERE drive = $1`,
+ [tree.drive, seed]
+ )
+
+ const replaceClient = await pool.connect()
+ let replacedAt: string
+ try {
+ const published = await writer(replaceClient).replace({
+ drive: tree.drive,
+ resourceId: tree.child,
+ ifMatch: 0,
+ content: Buffer.from('replacement'),
+ })
+ expect(published.updatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T.*Z$/)
+ expect(new Date(published.updatedAt).getTime()).toBeGreaterThan(new Date(seed).getTime())
+ replacedAt = published.updatedAt
+ } finally {
+ replaceClient.release()
+ }
+
+ const afterReplace = await pool.query<{ id: string; updated_at: Date }>(
+ `SELECT resource_id::text AS id, updated_at FROM gfs_resources WHERE drive = $1`,
+ [tree.drive]
+ )
+ const byId = Object.fromEntries(
+ afterReplace.rows.map(row => [row.id, row.updated_at.toISOString()])
+ )
+ expect(new Date(byId[tree.child] ?? 0).getTime()).toBeGreaterThan(new Date(seed).getTime())
+ expect(byId[tree.source]).toBe(new Date(seed).toISOString())
+
+ const moveClient = await pool.connect()
+ try {
+ await begin(moveClient)
+ await move(moveClient, tree, tree.destinationA)
+ await moveClient.query('COMMIT')
+ } finally {
+ moveClient.release()
+ }
+
+ const afterMove = await pool.query<{ child_at: Date; parent_at: Date }>(
+ `SELECT
+ (SELECT updated_at FROM gfs_resources WHERE resource_id = $1) AS child_at,
+ (SELECT updated_at FROM gfs_resources WHERE resource_id = $2) AS parent_at`,
+ [tree.child, tree.source]
+ )
+ expect(afterMove.rows[0]?.child_at.getTime()).toBeGreaterThan(new Date(replacedAt).getTime())
+ expect(afterMove.rows[0]?.parent_at.toISOString()).toBe(new Date(seed).toISOString())
+ }, 20_000)
})
diff --git a/control-api/test/routes.externalGfs.test.ts b/control-api/test/routes.externalGfs.test.ts
index 41f1eba7b..0289e4a76 100644
--- a/control-api/test/routes.externalGfs.test.ts
+++ b/control-api/test/routes.externalGfs.test.ts
@@ -526,7 +526,16 @@ describe('linked Desktop operator authority contract', () => {
if (lifecycle) return lifecycle
if (text.includes('parent_resource_id IS NULL')) {
return {
- rows: [{ resource_id: R, drive: 'main', name: '', kind: 'directory', path_cache: '/' }],
+ rows: [
+ {
+ resource_id: R,
+ drive: 'main',
+ name: '',
+ kind: 'directory',
+ path_cache: '/',
+ updated_at: new Date('2026-01-01T00:00:00.000Z'),
+ },
+ ],
}
}
if (text.includes('parent_resource_id = $2::uuid')) {
@@ -539,6 +548,7 @@ describe('linked Desktop operator authority contract', () => {
path_cache: '/all-operator-visible',
bytes: 0,
version: 1,
+ updated_at: new Date('2026-01-01T00:00:00.000Z'),
},
],
}
@@ -554,7 +564,13 @@ describe('linked Desktop operator authority contract', () => {
expect(res.body).toEqual({
ok: true,
data: {
- items: [expect.objectContaining({ resourceId: R2, name: 'all-operator-visible' })],
+ items: [
+ expect.objectContaining({
+ resourceId: R2,
+ name: 'all-operator-visible',
+ updatedAt: '2026-01-01T00:00:00.000Z',
+ }),
+ ],
nextCursor: null,
rootResourceId: R,
view: 'operator',
@@ -1842,6 +1858,7 @@ describe('GET /external/gfs/resources', () => {
path_cache: '/team-folder-tree',
version: 1,
bytes: 0,
+ updated_at: new Date('2026-01-01T00:00:00.000Z'),
sources: ['grant'],
permissions: ['read'],
covers_descendants: true,
@@ -1855,6 +1872,7 @@ describe('GET /external/gfs/resources', () => {
path_cache: '/other-org/external-file.pdf',
version: 2,
bytes: 128,
+ updated_at: new Date('2026-06-01T12:00:00.000Z'),
sources: ['share'],
permissions: ['read'],
covers_descendants: false,
@@ -1877,6 +1895,7 @@ describe('GET /external/gfs/resources', () => {
kind: 'directory',
sources: ['grant'],
coversDescendants: true,
+ updatedAt: '2026-01-01T00:00:00.000Z',
}),
expect.objectContaining({
resourceId: R2,
@@ -1884,6 +1903,7 @@ describe('GET /external/gfs/resources', () => {
kind: 'file',
sources: ['share'],
coversDescendants: false,
+ updatedAt: '2026-06-01T12:00:00.000Z',
}),
])
})
diff --git a/desktop-app/src/gfs/uriHandler.ts b/desktop-app/src/gfs/uriHandler.ts
index 20de03957..454167375 100644
--- a/desktop-app/src/gfs/uriHandler.ts
+++ b/desktop-app/src/gfs/uriHandler.ts
@@ -71,6 +71,8 @@ export interface ResolvedGfsResource {
path?: string | null
version: number
bytes?: number
+ /** ISO 8601 UTC from gfs_resources.updated_at. Optional during mixed-version deploys. */
+ updatedAt?: string
}
type GfsEnvelope<T> =
@@ -107,6 +109,8 @@ export interface GfsResourceView {
path: string | null
version: number
bytes: number
+ /** ISO 8601 UTC. Optional while older backends omit the additive field. */
+ updatedAt?: string
}
export interface GfsChildrenPage {
diff --git a/desktop-app/src/renderer.d.ts b/desktop-app/src/renderer.d.ts
index a956126ba..84e4d0818 100644
--- a/desktop-app/src/renderer.d.ts
+++ b/desktop-app/src/renderer.d.ts
@@ -121,6 +121,7 @@ declare global {
path?: string | null
version: number
bytes?: number
+ updatedAt?: string
}>
download: (uri: string) => Promise<{
resource: {
@@ -135,6 +136,7 @@ declare global {
path?: string | null
version: number
bytes?: number
+ updatedAt?: string
}
bytes: ArrayBuffer
}>
@@ -153,6 +155,7 @@ declare global {
path: string | null
version: number
bytes: number
+ updatedAt?: string
sources?: string[]
permissions?: string[]
coversDescendants?: boolean
@@ -177,6 +180,7 @@ declare global {
path: string | null
version: number
bytes: number
+ updatedAt?: string
}>
nextCursor: string | null
}>
diff --git a/desktop-app/test/gfsUriHandler.test.ts b/desktop-app/test/gfsUriHandler.test.ts
index 619119e89..b2ba890c7 100644
--- a/desktop-app/test/gfsUriHandler.test.ts
+++ b/desktop-app/test/gfsUriHandler.test.ts
@@ -145,6 +145,17 @@ describe('GfsClient.listChildren', () => {
)
expect(opts).toEqual({ token: 'tok' })
})
+
+ it('forwards updatedAt when present and keeps the field optional when omitted', async () => {
+ const withStamp = { ...CHILD, updatedAt: '2026-06-01T12:00:00.000Z' }
+ const requestJson = vi.fn(async () => ({
+ ok: true,
+ data: { items: [withStamp, CHILD], nextCursor: null },
+ })) as GfsTransport['requestJson']
+ const out = await new GfsClient(transport({ requestJson })).listChildren(RID, 'tok')
+ expect(out.items[0]?.updatedAt).toBe('2026-06-01T12:00:00.000Z')
+ expect(out.items[1]?.updatedAt).toBeUndefined()
+ })
})
describe('GfsClient.listAccessible', () => {
diff --git a/gfs-controller/src/api/read.test.ts b/gfs-controller/src/api/read.test.ts
index 7dde488bc..257648f75 100644
--- a/gfs-controller/src/api/read.test.ts
+++ b/gfs-controller/src/api/read.test.ts
@@ -35,6 +35,7 @@ function resource(partial: Partial<GfsResource> & { resourceId: string; name: st
blobKey: null,
contentSha256: null,
deletedAt: null,
+ updatedAt: "2026-01-01T00:00:00.000Z",
...partial,
};
}
@@ -343,4 +344,31 @@ describe("toView", () => {
expect(view.gfsUri).toBe(`gfs://main/${rid(9)}`);
expect(view.path).toBe("/org/n");
});
+
+ it("exposes updatedAt as an ISO 8601 UTC string", () => {
+ const view = toView(
+ resource({ resourceId: rid(9), name: "n", updatedAt: "2026-06-01T12:00:00.000Z" })
+ );
+ expect(view.updatedAt).toBe("2026-06-01T12:00:00.000Z");
+ expect(view.updatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T.*Z$/);
+ });
+});
+
+describe("listChildren timestamp projection", () => {
+ it("includes updatedAt on every listed item without putting it in the cursor", async () => {
+ const stamp = "2026-06-01T12:00:00.000Z";
+ const store = new FakeStore()
+ .add(resource({ resourceId: rid(1), name: "root", kind: "directory" }))
+ .add(
+ resource({
+ resourceId: rid(2),
+ name: "a",
+ parentResourceId: rid(1),
+ updatedAt: stamp,
+ })
+ );
+ const page = await listChildren(store, "main", rid(1), { limit: 10 });
+ expect(page.items[0]?.updatedAt).toBe(stamp);
+ expect(page.nextCursor).toBeNull();
+ });
});
diff --git a/gfs-controller/src/api/read.ts b/gfs-controller/src/api/read.ts
index 61af5f4cb..ff285e7d2 100644
--- a/gfs-controller/src/api/read.ts
+++ b/gfs-controller/src/api/read.ts
@@ -17,6 +17,8 @@ export interface GfsResource {
/** Digest of the committed generation. Never exposed in GfsResourceView. */
contentSha256: string | null;
deletedAt: string | null;
+ /** ISO 8601 UTC from gfs_resources.updated_at. Always present on live rows. */
+ updatedAt: string;
}
/** Public view returned to clients — includes the canonical gfs:// URI. */
@@ -31,6 +33,7 @@ export interface GfsResourceView {
path: string | null;
version: number;
bytes: number;
+ updatedAt: string;
}
/**
@@ -101,6 +104,7 @@ export function toView(resource: GfsResource): GfsResourceView {
path: resource.pathCache,
version: resource.version,
bytes: resource.bytes,
+ updatedAt: resource.updatedAt,
};
}
diff --git a/gfs-controller/src/api/serve.copy.test.ts b/gfs-controller/src/api/serve.copy.test.ts
index c2ea14e9c..71cc173f2 100644
--- a/gfs-controller/src/api/serve.copy.test.ts
+++ b/gfs-controller/src/api/serve.copy.test.ts
@@ -61,6 +61,7 @@ function fixture(options: { child?: boolean; snapshotCount?: number; omitLastPar
resourceId: "10000000-0000-4000-8000-000000000001", drive: "main", parentResourceId: DEST,
name: "source-copy", kind: "directory" as const, pathCache: "/archive/source-copy", version: 0,
bytes: 0, blobKey: null, contentSha256: null, deletedAt: null,
+ updatedAt: "2026-01-01T00:00:00.000Z",
}, requestId: input.requestId, objectCount: snapshot.length, fileCount: 0,
folderCount: snapshot.length, totalBytes: 0n };
});
diff --git a/gfs-controller/src/api/serve.rename.test.ts b/gfs-controller/src/api/serve.rename.test.ts
index f97faadb7..c5ccbd849 100644
--- a/gfs-controller/src/api/serve.rename.test.ts
+++ b/gfs-controller/src/api/serve.rename.test.ts
@@ -36,6 +36,7 @@ function fixture(options: { allowed?: boolean } = {}) {
const rename = vi.fn(async (_input: unknown) => ({
resourceId: RID, drive: "main", parentResourceId: PARENT, name: "renamed", kind: "directory" as const,
pathCache: "/docs/renamed", version: 5, bytes: 0, blobKey: null, contentSha256: null, deletedAt: null,
+ updatedAt: "2026-01-01T00:00:00.000Z",
}));
const deps: ServingDeps = {
verifyToken: () => claims,
diff --git a/gfs-controller/src/api/serve.test.ts b/gfs-controller/src/api/serve.test.ts
index 46ddf9b52..b0c9ab9ba 100644
--- a/gfs-controller/src/api/serve.test.ts
+++ b/gfs-controller/src/api/serve.test.ts
@@ -99,6 +99,7 @@ const FILE: GfsResource = {
blobKey: null,
contentSha256: null,
deletedAt: null,
+ updatedAt: "2026-01-01T00:00:00.000Z",
};
const DIR: GfsResource = {
...FILE,
diff --git a/gfs-controller/src/authz/accessibleStore.test.ts b/gfs-controller/src/authz/accessibleStore.test.ts
index 7243ddba1..ec821ff72 100644
--- a/gfs-controller/src/authz/accessibleStore.test.ts
+++ b/gfs-controller/src/authz/accessibleStore.test.ts
@@ -45,6 +45,7 @@ describe("AccessibleResourceStore", () => {
path_cache: "/reports",
version: 1,
bytes: 0,
+ updated_at: new Date("2026-01-01T00:00:00.000Z"),
sources: ["operator"],
permissions: ["read", "write", "delete", "manage_acl", "share"],
covers_descendants: true,
@@ -54,6 +55,7 @@ describe("AccessibleResourceStore", () => {
const page = await new AccessibleResourceStore(storeDb).list(operatorCtx, { limit: 1 });
expect(storeDb.queries[0]).toContain("FROM gfs_resources r");
+ expect(storeDb.queries[0]).toContain("r.updated_at");
expect(storeDb.queries[0]).not.toContain("gfs_grants");
expect(storeDb.values[0]).toEqual(["main", null, null, 2]);
expect(page.nextCursor).toBeNull();
@@ -63,6 +65,7 @@ describe("AccessibleResourceStore", () => {
rid: RID_A.replaceAll("-", ""),
gfsUri: `gfs://main/${RID_A.replaceAll("-", "")}`,
name: "reports",
+ updatedAt: "2026-01-01T00:00:00.000Z",
permissions: ["read", "write", "delete", "manage_acl", "share"],
sources: ["operator"],
coversDescendants: true,
@@ -81,6 +84,7 @@ describe("AccessibleResourceStore", () => {
path_cache: "/reports/shared.md",
version: 2,
bytes: 12,
+ updated_at: new Date("2026-06-01T12:00:00.000Z"),
permissions: ["read"],
sources: ["grant"],
covers_descendants: false,
@@ -91,6 +95,7 @@ describe("AccessibleResourceStore", () => {
expect(storeDb.queries[0]).toContain("gfs_grants");
expect(storeDb.queries[0]).toContain("gfs_shares");
+ expect(storeDb.queries[0]).toContain("r.updated_at");
expect(storeDb.values[0]?.[1]).toEqual(["user", "team"]);
expect(storeDb.values[0]?.[2]).toEqual(["user-1", "team-1"]);
expect(page.items[0]).toMatchObject({
@@ -98,6 +103,8 @@ describe("AccessibleResourceStore", () => {
permissions: ["read"],
sources: ["grant"],
coversDescendants: false,
+ updatedAt: "2026-06-01T12:00:00.000Z",
});
+ expect(storeDb.queries[0]).toContain("GROUP BY r.resource_id, r.drive, r.parent_resource_id, r.name, r.kind, r.path_cache, r.version, r.bytes, r.updated_at");
});
});
diff --git a/gfs-controller/src/authz/accessibleStore.ts b/gfs-controller/src/authz/accessibleStore.ts
index e26d84904..b021866e6 100644
--- a/gfs-controller/src/authz/accessibleStore.ts
+++ b/gfs-controller/src/authz/accessibleStore.ts
@@ -12,6 +12,7 @@ export interface AccessibleResource {
path: string | null;
version: number;
bytes: number;
+ updatedAt: string;
permissions: string[];
sources: string[];
coversDescendants: boolean;
@@ -63,6 +64,15 @@ function clampLimit(raw: unknown): number {
return Math.min(Math.floor(n), 1000);
}
+function toIsoTimestamp(value: unknown): string {
+ if (value instanceof Date) return value.toISOString();
+ if (typeof value === "string" && value.length > 0) {
+ const parsed = new Date(value);
+ return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString();
+ }
+ throw new Error("gfs_resources.updated_at is required");
+}
+
function rowToAccessibleResource(row: {
resource_id: string;
drive: string;
@@ -72,6 +82,7 @@ function rowToAccessibleResource(row: {
path_cache: string | null;
version: number;
bytes: number;
+ updated_at: unknown;
permissions: string[];
sources: string[];
covers_descendants: boolean;
@@ -88,6 +99,7 @@ function rowToAccessibleResource(row: {
path: row.path_cache,
version: row.version,
bytes: row.bytes,
+ updatedAt: toIsoTimestamp(row.updated_at),
permissions: row.permissions ?? [],
sources: row.sources ?? [],
coversDescendants: Boolean(row.covers_descendants),
@@ -136,6 +148,7 @@ export class AccessibleResourceStore {
r.path_cache,
r.version,
r.bytes,
+ r.updated_at,
array_remove(array_agg(DISTINCT a.source), NULL) AS sources,
array_remove(array_agg(DISTINCT p.permission), NULL) AS permissions,
bool_or(a.covers_descendants) AS covers_descendants
@@ -144,7 +157,7 @@ export class AccessibleResourceStore {
ON r.drive = $1 AND r.resource_id = a.resource_id AND r.deleted_at IS NULL
LEFT JOIN LATERAL unnest(a.permissions) AS p(permission) ON true
WHERE ($4::text IS NULL OR (r.name, r.resource_id) > ($4, $5::uuid))
- GROUP BY r.resource_id, r.drive, r.parent_resource_id, r.name, r.kind, r.path_cache, r.version, r.bytes
+ GROUP BY r.resource_id, r.drive, r.parent_resource_id, r.name, r.kind, r.path_cache, r.version, r.bytes, r.updated_at
ORDER BY r.name, r.resource_id
LIMIT $6`,
[
@@ -166,6 +179,7 @@ export class AccessibleResourceStore {
path_cache: string | null;
version: number;
bytes: number;
+ updated_at: unknown;
permissions: string[];
sources: string[];
covers_descendants: boolean;
@@ -195,6 +209,7 @@ export class AccessibleResourceStore {
r.path_cache,
r.version,
r.bytes,
+ r.updated_at,
ARRAY['operator']::text[] AS sources,
ARRAY['read','write','delete','manage_acl','share']::text[] AS permissions,
true AS covers_descendants
@@ -216,6 +231,7 @@ export class AccessibleResourceStore {
path_cache: string | null;
version: number;
bytes: number;
+ updated_at: unknown;
sources: string[];
permissions: string[];
covers_descendants: boolean;
diff --git a/gfs-controller/src/db/blobStaging.ts b/gfs-controller/src/db/blobStaging.ts
index 54216730b..fa10e385e 100644
--- a/gfs-controller/src/db/blobStaging.ts
+++ b/gfs-controller/src/db/blobStaging.ts
@@ -208,7 +208,7 @@ export class PgBlobStagingStore {
): Promise<Record<string, unknown> | null> {
const result = await this.db.query(
`SELECT resource_id, drive, parent_resource_id, name, kind, path_cache,
- version, bytes, blob_key, content_sha256, deleted_at
+ version, bytes, blob_key, content_sha256, deleted_at, updated_at
FROM gfs_resources
WHERE drive = $1 AND resource_id = $2 AND blob_key = $3`,
[drive, resourceId, blobKey]
@@ -225,7 +225,7 @@ export class PgBlobStagingStore {
}
const result = await manifestQuery(this.db,
`SELECT resource_id, drive, parent_resource_id, name, kind, path_cache,
- version, bytes, blob_key, content_sha256, deleted_at
+ version, bytes, blob_key, content_sha256, deleted_at, updated_at
FROM gfs_resources
WHERE drive = $1 AND resource_id = ANY($2::uuid[])`,
[drive, ids],
diff --git a/gfs-controller/src/db/copyPublication.ts b/gfs-controller/src/db/copyPublication.ts
index acbcbeada..1abb2923e 100644
--- a/gfs-controller/src/db/copyPublication.ts
+++ b/gfs-controller/src/db/copyPublication.ts
@@ -29,7 +29,7 @@ export interface CopyPublicationResult {
totalBytes: bigint;
}
-const RETURNING = "resource_id, drive, parent_resource_id, name, kind, path_cache, version, bytes, blob_key, content_sha256, deleted_at";
+const RETURNING = "resource_id, drive, parent_resource_id, name, kind, path_cache, version, bytes, blob_key, content_sha256, deleted_at, updated_at";
const AMBIGUOUS_COMMIT_INSPECTION_MS = 2_000;
const POST_FAILURE_AUDIT_MS = 2_000;
@@ -91,11 +91,21 @@ function sameChildren(rows: Record<string, unknown>[], expected: CopyDestination
return actual.every((value, index) => value === wanted[index]);
}
-function resource(ref: PublishedTreeRef, drive: string): GfsResource {
+function toIsoTimestamp(value: unknown): string {
+ if (value instanceof Date) return value.toISOString();
+ if (typeof value === "string" && value.length > 0) {
+ const parsed = new Date(value);
+ return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString();
+ }
+ throw new Error("gfs_resources.updated_at is required");
+}
+
+function resource(ref: PublishedTreeRef, drive: string, updatedAt: string): GfsResource {
return {
resourceId: ref.resourceId, drive, parentResourceId: ref.parentResourceId,
name: ref.name, kind: ref.kind, pathCache: ref.pathCache, version: 0,
bytes: Number(ref.bytes), blobKey: ref.blobKey, contentSha256: ref.contentSha256, deletedAt: null,
+ updatedAt,
};
}
@@ -230,8 +240,8 @@ function insertSql(nodes: readonly ReservedNode[]): { sql: string; values: unkno
};
}
-function result(input: CopyInput, root: PublishedTreeRef): CopyPublicationResult {
- return { root: resource(root, input.drive), requestId: input.requestId, objectCount: input.plan.objectCount,
+function result(input: CopyInput, root: PublishedTreeRef, updatedAt: string): CopyPublicationResult {
+ return { root: resource(root, input.drive, updatedAt), requestId: input.requestId, objectCount: input.plan.objectCount,
fileCount: input.plan.fileCount, folderCount: input.plan.folderCount, totalBytes: input.plan.totalBytes };
}
@@ -318,12 +328,15 @@ export async function publishCopy(deps: Dependencies, input: CopyInput): Promise
stagedKeys.push(staged.blobKey);
}
const root = reserved[0];
+ let publishedUpdatedAt: string | undefined;
await deps.tx.transaction(async client => {
await revalidate(client, input);
deadline(input);
const insert = insertSql(reserved);
try {
- await client.query(insert.sql, insert.values);
+ const inserted = await client.query(insert.sql, insert.values);
+ const rootRow = inserted.rows.find(row => String(row.resource_id) === root.resourceId);
+ publishedUpdatedAt = toIsoTimestamp(rootRow?.updated_at);
} catch (error) {
if ((error as { code?: string }).code === "23505") {
throw new GfsError("already_exists", `a resource named '${input.plan.rootName}' already exists here`);
@@ -337,7 +350,7 @@ export async function publishCopy(deps: Dependencies, input: CopyInput): Promise
await deps.manifests.removeCommittedMany(input.requestId, stagedKeys, {
deadlineAtMs: input.deadlineAtMs, signal: input.signal, now: input.now,
}).catch(() => undefined);
- return result(input, root);
+ return result(input, root, publishedUpdatedAt ?? new Date().toISOString());
} catch (error) {
if ((error as Error).name === "CommitOutcomeUnknownError") {
// COMMIT uncertainty is resolved with a fresh, short budget. The request
@@ -347,7 +360,7 @@ export async function publishCopy(deps: Dependencies, input: CopyInput): Promise
const outcome = await inspectAmbiguous(deps, input, reserved, recoveryBudget);
if (outcome === "full") {
await deps.manifests.removeCommittedMany(input.requestId, stagedKeys, ambiguousCommitBudget()).catch(() => undefined);
- return result(input, reserved[0]);
+ return result(input, reserved[0], new Date().toISOString());
}
if (outcome === "zero") {
await cleanup(deps, ambiguousCommitBudget(), stagedKeys);
diff --git a/gfs-controller/src/db/renamePublication.realPostgres.integration.test.ts b/gfs-controller/src/db/renamePublication.realPostgres.integration.test.ts
index 46dd7cdb5..1b01147e1 100644
--- a/gfs-controller/src/db/renamePublication.realPostgres.integration.test.ts
+++ b/gfs-controller/src/db/renamePublication.realPostgres.integration.test.ts
@@ -127,6 +127,7 @@ describeRealPostgres("renamePublication on real PostgreSQL", () => {
});
expect(renamed.name).toBe("archive");
+ expect(renamed.updatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T.*Z$/);
const rows = await pool.query(
`SELECT resource_id::text AS id, name, path_cache, version
@@ -142,6 +143,55 @@ describeRealPostgres("renamePublication on real PostgreSQL", () => {
});
});
+ it("advances updatedAt on rename and leaves an untouched parent at the seeded timestamp", async () => {
+ const seed = "2000-01-01T00:00:00.000Z";
+ const seeded = await pool.query(`
+ WITH drive_root AS (
+ INSERT INTO gfs_resources (drive, parent_resource_id, name, kind, path_cache, updated_at)
+ VALUES ('stamp', NULL, '', 'directory', '/', $1::timestamptz)
+ RETURNING resource_id
+ ),
+ parent AS (
+ INSERT INTO gfs_resources (drive, parent_resource_id, name, kind, path_cache, updated_at)
+ SELECT 'stamp', resource_id, 'docs', 'directory', '/docs', $1::timestamptz FROM drive_root
+ RETURNING resource_id
+ ),
+ target AS (
+ INSERT INTO gfs_resources (drive, parent_resource_id, name, kind, path_cache, version, updated_at)
+ SELECT 'stamp', resource_id, 'old', 'directory', '/docs/old', 1, $1::timestamptz FROM parent
+ RETURNING resource_id
+ )
+ SELECT parent.resource_id::text AS parent_id, target.resource_id::text AS target_id
+ FROM parent, target;
+ `, [seed]);
+ const { parent_id: parentId, target_id: targetId } = seeded.rows[0] as {
+ parent_id: string;
+ target_id: string;
+ };
+
+ const renamed = await publishRename(tx, {
+ requestId: "req-rename-updated-at",
+ subject: "host:1st:mcp-host/agent-a",
+ audit: noopAudit,
+ drive: "stamp",
+ resourceId: targetId,
+ newName: "new",
+ ifMatch: 1,
+ maxObjects: 1000,
+ deadlineAtMs: Date.now() + 30_000,
+ });
+ expect(new Date(renamed.updatedAt).getTime()).toBeGreaterThan(new Date(seed).getTime());
+
+ const rows = await pool.query(
+ `SELECT resource_id::text AS id, updated_at
+ FROM gfs_resources WHERE drive = 'stamp' AND resource_id = ANY($1::uuid[])`,
+ [[parentId, targetId]]
+ );
+ const byId = new Map(rows.rows.map(row => [row.id as string, (row.updated_at as Date).toISOString()]));
+ expect(byId.get(parentId)).toBe(new Date(seed).toISOString());
+ expect(new Date(byId.get(targetId) ?? 0).getTime()).toBeGreaterThan(new Date(seed).getTime());
+ });
+
// The admission bounds run through the REAL transactor here: PgTransactor
// arms statement_timeout on a live session and gates acquisition on the
// deadline, so both paths execute against the actual PostgreSQL parser and
diff --git a/gfs-controller/src/db/renamePublication.test.ts b/gfs-controller/src/db/renamePublication.test.ts
index a14dc436d..91da1d481 100644
--- a/gfs-controller/src/db/renamePublication.test.ts
+++ b/gfs-controller/src/db/renamePublication.test.ts
@@ -95,7 +95,7 @@ describe("transactional rename publication", () => {
it("renames root and subtree paths while preserving identity, parent, drive and blob", async () => {
const f = fixture(); const beforeChild = { ...f.db.tree[1] };
const renamed = await f.writes.rename(f.input);
- expect(renamed).toMatchObject({ resourceId: TARGET, parentResourceId: PARENT, drive: "main", name: "new", pathCache: "/docs/new", version: 5 });
+ expect(renamed).toMatchObject({ resourceId: TARGET, parentResourceId: PARENT, drive: "main", name: "new", pathCache: "/docs/new", version: 5, updatedAt: "2026-07-17T00:00:01.000Z" });
expect(f.db.tree[1]).toMatchObject({ resource_id: CHILD, parent_resource_id: TARGET, path_cache: "/docs/new/file.txt",
version: beforeChild.version, blob_key: beforeChild.blob_key, content_sha256: beforeChild.content_sha256 });
expect(f.audit.calls).toHaveLength(1);
diff --git a/gfs-controller/src/db/renamePublication.ts b/gfs-controller/src/db/renamePublication.ts
index 2edfbef17..f6a60fb50 100644
--- a/gfs-controller/src/db/renamePublication.ts
+++ b/gfs-controller/src/db/renamePublication.ts
@@ -76,9 +76,11 @@ function row(value: Record<string, unknown>): Row {
}
function resource(value: Row): GfsResource {
+ if (!value.updatedAt) throw new Error("rename returned a resource without updatedAt");
return { resourceId: value.resourceId, drive: value.drive, parentResourceId: value.parentResourceId,
name: value.name, kind: value.kind, pathCache: value.pathCache, version: value.version,
- bytes: value.bytes, blobKey: value.blobKey, contentSha256: value.contentSha256, deletedAt: value.deletedAt };
+ bytes: value.bytes, blobKey: value.blobKey, contentSha256: value.contentSha256, deletedAt: value.deletedAt,
+ updatedAt: value.updatedAt };
}
function same(a: readonly Row[], b: readonly Row[]): boolean {
diff --git a/gfs-controller/src/db/resourceStore.test.ts b/gfs-controller/src/db/resourceStore.test.ts
index 0201f7555..ffdfc2b20 100644
--- a/gfs-controller/src/db/resourceStore.test.ts
+++ b/gfs-controller/src/db/resourceStore.test.ts
@@ -45,6 +45,7 @@ function pgRow(over: Record<string, unknown> = {}): Record<string, unknown> {
blob_key: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/11111111-1111-4111-8111-111111111111",
content_sha256: "b".repeat(64),
deleted_at: null,
+ updated_at: new Date("2026-01-01T00:00:00.000Z"),
...over,
};
}
@@ -68,12 +69,25 @@ describe("PgResourceStore.getResource", () => {
blobKey: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/11111111-1111-4111-8111-111111111111",
contentSha256: "b".repeat(64),
deletedAt: null,
+ updatedAt: "2026-01-01T00:00:00.000Z",
});
expect(typeof res?.bytes).toBe("number");
+ expect(res?.updatedAt).toBe("2026-01-01T00:00:00.000Z");
+ expect(db.calls[0].text).toContain("updated_at");
// Parameterized: never string-interpolates the id.
expect(db.calls[0].values).toEqual(["main", "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"]);
});
+ it("coerces TIMESTAMPTZ updated_at Date values to ISO 8601 UTC", async () => {
+ const db = fakeDb([[pgRow({ updated_at: new Date("2026-06-01T12:00:00.000Z") })]]);
+ const res = await new PgResourceStore(db).getResource(
+ "main",
+ "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
+ );
+ expect(res?.updatedAt).toBe("2026-06-01T12:00:00.000Z");
+ expect(res?.updatedAt).toMatch(/^\d{4}-\d{2}-\d{2}T.*Z$/);
+ });
+
it("maps legacy rows with no generation pointer without inventing one", async () => {
const db = fakeDb([[pgRow({ blob_key: null, content_sha256: null })]]);
const resource = await new PgResourceStore(db).getResource(
diff --git a/gfs-controller/src/db/resourceStore.ts b/gfs-controller/src/db/resourceStore.ts
index 78139df72..f07f94151 100644
--- a/gfs-controller/src/db/resourceStore.ts
+++ b/gfs-controller/src/db/resourceStore.ts
@@ -14,8 +14,8 @@ import { withDeadlineTransaction, type DeadlineBudget, type DeadlineClient } fro
*
* Two node-postgres type quirks are normalized here so callers see clean JS
* values: a `BIGINT` (`bytes`) comes back as a string, and a `TIMESTAMPTZ`
- * (`deleted_at`) comes back as a Date — both are coerced to the shapes
- * GfsResource declares (`number`, ISO `string | null`).
+ * (`deleted_at`, `updated_at`) comes back as a Date — both are coerced to the
+ * shapes GfsResource declares (`number`, ISO `string | null` / ISO `string`).
*/
/** Minimal query surface — a pg Pool satisfies this; tests inject a fake. */
@@ -47,6 +47,15 @@ function toIsoOrNull(value: unknown): string | null {
return String(value);
}
+function toIsoTimestamp(value: unknown): string {
+ if (value instanceof Date) return value.toISOString();
+ if (typeof value === "string" && value.length > 0) {
+ const parsed = new Date(value);
+ return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString();
+ }
+ throw new Error("gfs_resources.updated_at is required");
+}
+
function rowToResource(row: Record<string, unknown>): GfsResource {
return {
resourceId: String(row.resource_id),
@@ -60,6 +69,7 @@ function rowToResource(row: Record<string, unknown>): GfsResource {
blobKey: row.blob_key == null ? null : String(row.blob_key),
contentSha256: row.content_sha256 == null ? null : String(row.content_sha256),
deletedAt: toIsoOrNull(row.deleted_at),
+ updatedAt: toIsoTimestamp(row.updated_at),
};
}
@@ -83,7 +93,7 @@ function rowToCopyNode(row: Record<string, unknown>): CopySnapshotNode {
}
const SELECT_COLUMNS =
- "resource_id, drive, parent_resource_id, name, kind, path_cache, version, bytes, blob_key, content_sha256, deleted_at";
+ "resource_id, drive, parent_resource_id, name, kind, path_cache, version, bytes, blob_key, content_sha256, deleted_at, updated_at";
function toDbResourceId(resourceId: string): string {
const rid = normalizeResourceId(resourceId);
diff --git a/gfs-controller/src/db/writeStore.generation.test.ts b/gfs-controller/src/db/writeStore.generation.test.ts
index 16cd6f0cf..72026698f 100644
--- a/gfs-controller/src/db/writeStore.generation.test.ts
+++ b/gfs-controller/src/db/writeStore.generation.test.ts
@@ -30,6 +30,7 @@ function row(over: Record<string, unknown> = {}): Record<string, unknown> {
blob_key: null,
content_sha256: null,
deleted_at: null,
+ updated_at: new Date("2026-01-01T00:00:00.000Z"),
...over,
};
}
diff --git a/gfs-controller/src/db/writeStore.test.ts b/gfs-controller/src/db/writeStore.test.ts
index 14e644944..10f18a968 100644
--- a/gfs-controller/src/db/writeStore.test.ts
+++ b/gfs-controller/src/db/writeStore.test.ts
@@ -31,6 +31,7 @@ function row(over: Record<string, unknown> = {}): Record<string, unknown> {
blob_key: null,
content_sha256: null,
deleted_at: null,
+ updated_at: new Date("2026-01-01T00:00:00.000Z"),
...over,
};
}
@@ -144,8 +145,9 @@ describe("GfsWriteService.create legacy contract", () => {
});
const blobs = new RecordingBlobs();
const created = await service(client, blobs).create({ drive: "main", parentId: PARENT, name: "new.txt", content: Buffer.from("hello") });
- expect(created).toMatchObject({ name: "new.txt", pathCache: "/docs/new.txt", version: 0, bytes: 5 });
+ expect(created).toMatchObject({ name: "new.txt", pathCache: "/docs/new.txt", version: 0, bytes: 5, updatedAt: "2026-01-01T00:00:00.000Z" });
const insert = client.calls.find(call => call.sql.includes("INSERT INTO gfs_resources"))!;
+ expect(insert.sql).toContain("updated_at");
expect(insert.values.slice(1, 7)).toEqual(["main", PARENT, "new.txt", "file", "/docs/new.txt", 5]);
expect(blobs.writes).toEqual([{ resourceId: RESOURCE, bytes: 5 }]);
expect(client.calls[0].sql).toContain("hashtext('gfs:structure:' || $1)::bigint");
@@ -238,7 +240,8 @@ describe("GfsWriteService.replace legacy contract", () => {
it("bumps version and bytes under a resource row lock", async () => {
const client = new FakeClient({ lock: () => [row({ version: 3 })], update: values => [row({ version: 4, bytes: values[2], blob_key: values[3], content_sha256: values[4] })] });
const updated = await service(client).replace({ drive: "main", resourceId: RESOURCE, ifMatch: 3, content: Buffer.from("howdy") });
- expect(updated).toMatchObject({ resourceId: RESOURCE, version: 4, bytes: 5 });
+ expect(updated).toMatchObject({ resourceId: RESOURCE, version: 4, bytes: 5, updatedAt: "2026-01-01T00:00:00.000Z" });
+ expect(client.calls.find(call => call.sql.includes("UPDATE gfs_resources"))?.sql).toContain("updated_at");
expect(client.calls.some(call => call.sql.includes("'legacy_flat'"))).toBe(true);
});
diff --git a/gfs-controller/src/db/writeStore.ts b/gfs-controller/src/db/writeStore.ts
index 350320e30..bcad42a4b 100644
--- a/gfs-controller/src/db/writeStore.ts
+++ b/gfs-controller/src/db/writeStore.ts
@@ -144,7 +144,7 @@ export interface BlobWriter {
}
const RETURNING =
- "resource_id, drive, parent_resource_id, name, kind, path_cache, version, bytes, blob_key, content_sha256, deleted_at";
+ "resource_id, drive, parent_resource_id, name, kind, path_cache, version, bytes, blob_key, content_sha256, deleted_at, updated_at";
interface AncestorRow {
resourceId: string;
@@ -162,6 +162,15 @@ function toIsoOrNull(value: unknown): string | null {
return String(value);
}
+function toIsoTimestamp(value: unknown): string {
+ if (value instanceof Date) return value.toISOString();
+ if (typeof value === "string" && value.length > 0) {
+ const parsed = new Date(value);
+ return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString();
+ }
+ throw new Error("gfs_resources.updated_at is required");
+}
+
function rowToResource(row: Record<string, unknown>): GfsResource {
return {
resourceId: String(row.resource_id),
@@ -175,6 +184,7 @@ function rowToResource(row: Record<string, unknown>): GfsResource {
blobKey: row.blob_key == null ? null : String(row.blob_key),
contentSha256: row.content_sha256 == null ? null : String(row.content_sha256),
deletedAt: toIsoOrNull(row.deleted_at),
+ updatedAt: toIsoTimestamp(row.updated_at),
};
}
diff --git a/gfs-controller/test/copyPublicationTestKit.ts b/gfs-controller/test/copyPublicationTestKit.ts
index 41a6bb24f..c7f6040d0 100644
--- a/gfs-controller/test/copyPublicationTestKit.ts
+++ b/gfs-controller/test/copyPublicationTestKit.ts
@@ -143,7 +143,12 @@ export class CopyDb implements TxClient {
blob_key: values[offset + 7], content_sha256: values[offset + 8], version: values[offset + 9] };
});
for (const value of inserted) {
- const row = { ...value, bytes: Number(value.bytes), deleted_at: null };
+ const row = {
+ ...value,
+ bytes: Number(value.bytes),
+ deleted_at: null,
+ updated_at: new Date("2026-01-01T00:00:00.000Z"),
+ };
this.resources.set(String(row.resource_id), row); rows.push(row);
}
return { rows };