mcp-for-i 0.1.13 → 0.2.0

package/dist/ibmi/IBMiContent.js

@@ -1,41 +1,25 @@
 import fs from "fs/promises";
 import path from "path";
 import os from "os";
+import crypto from "crypto";
 import { Tools } from "./Tools.js";
 import { IBMiClient } from "./client.js";
 import { SourceDateStore, makeAliasName } from "./sourceDates.js";
 export class IBMiContent {
     ibmi;
     sourceDates = new SourceDateStore();
+    snapshotCache = new Map();
+    snapshotInflight = new Map();
+    snapshotLatestKey = new Map();
+    snapshotGeneration = new Map();
+    snapshotCacheTtlMs = 120_000;
+    snapshotCacheMax = 32;
     constructor(ibmi) {
         this.ibmi = ibmi;
     }
     get config() {
         return this.ibmi.getConfig();
     }
-    async getTempLibrary() {
-        const desired = this.ibmi.upperCaseName(this.config.tempLibrary || "ILEDITOR");
-        if (desired === "QTEMP")
-            return "QTEMP";
-        try {
-            const rows = await this.ibmi.runSQL(`select SYSTEM_SCHEMA_NAME from QSYS2.SYSSCHEMAS where SYSTEM_SCHEMA_NAME=${Tools.sqlString(desired)}`);
-            if (rows.length > 0)
-                return desired;
-        }
-        catch {
-            // ignore and fall back to QTEMP
-        }
-        if (!this.config.readOnlyMode) {
-            try {
-                await this.createLibrary(desired);
-                return desired;
-            }
-            catch {
-                // ignore
-            }
-        }
-        return undefined;
-    }
     async downloadStreamfileRaw(remotePath) {
         const tmpFile = await this.createTempFile();
         await this.ibmi.client.getFile(tmpFile, remotePath);
@@ -81,11 +65,33 @@ export class IBMiContent {
         return files;
     }
     async downloadMemberContent(library, sourceFile, member) {
+        return (await this.downloadMemberContentDetailed(library, sourceFile, member)).content;
+    }
+    async downloadMemberContentDetailed(library, sourceFile, member) {
         if (this.config.enableSourceDates) {
-            const withDates = await this.downloadMemberContentWithDates(library, sourceFile, member);
-            if (withDates !== undefined)
-                return withDates;
+            try {
+                const lib = this.requireQsysName(library, "library");
+                const file = this.requireQsysName(sourceFile, "sourceFile");
+                const mbr = this.requireQsysName(member, "member");
+                const snapshot = await this.loadMemberSnapshotViaSql(lib, file, mbr);
+                return { content: snapshot.content, transport: "sql-member", warnings: [] };
+            }
+            catch (error) {
+                const fallback = await this.downloadMemberContentViaStreamFile(library, sourceFile, member);
+                return {
+                    content: fallback,
+                    transport: "cpytostmf",
+                    warnings: [`Source-date SQL read failed; used complete CPYTOSTMF fallback: ${error?.message || String(error)}`]
+                };
+            }
         }
+        return {
+            content: await this.downloadMemberContentViaStreamFile(library, sourceFile, member),
+            transport: "cpytostmf",
+            warnings: []
+        };
+    }
+    async downloadMemberContentViaStreamFile(library, sourceFile, member) {
         const lib = this.requireQsysName(library, "library");
         const file = this.requireQsysName(sourceFile, "sourceFile");
         const mbr = this.requireQsysName(member, "member");
@@ -93,17 +99,22 @@ export class IBMiContent {
         const ccsid = this.normalizeSourceFileCcsid(this.config.sourceFileCCSID);
         const cmd = `QSYS/CPYTOSTMF FROMMBR('${Tools.qualifyPath(lib, file, mbr, undefined, true)}') ` +
             `TOSTMF('${tempRemote}') STMFOPT(*REPLACE) STMFCCSID(1208) DBFCCSID(${ccsid})`;
-        const result = await this.ibmi.sendQsh({ command: `system \"${IBMiClient.escapeForShell(cmd)}\"` });
-        if (result.code !== 0)
-            throw new Error(result.stderr || "CPYTOSTMF failed");
-        const buffer = await this.downloadStreamfileRaw(tempRemote);
-        await this.ibmi.sendCommand({ command: `rm -f ${Tools.escapePath(tempRemote)}` });
-        return Buffer.from(buffer).toString("utf8");
+        try {
+            const result = await this.ibmi.sendQsh({ command: `system \"${IBMiClient.escapeForShell(cmd)}\"` });
+            if (result.code !== 0)
+                throw new Error(result.stderr || "CPYTOSTMF failed");
+            const buffer = await this.downloadStreamfileRaw(tempRemote);
+            return Buffer.from(buffer).toString("utf8");
+        }
+        finally {
+            await this.ibmi.sendCommand({ command: `rm -f ${Tools.escapePath(tempRemote)}` }).catch(() => { });
+        }
     }
     async uploadMemberContent(library, sourceFile, member, content) {
         if (this.config.enableSourceDates) {
             try {
                 await this.uploadMemberContentWithDates(library, sourceFile, member, content.toString());
+                this.invalidateMemberSnapshot(library, sourceFile, member);
                 return;
             }
             catch {
@@ -111,6 +122,7 @@ export class IBMiContent {
             }
         }
         await this.uploadMemberContentRaw(library, sourceFile, member, content);
+        this.invalidateMemberSnapshot(library, sourceFile, member);
     }
     async uploadMemberContentRaw(library, sourceFile, member, content) {
         this.assertWritable();
@@ -129,8 +141,24 @@ export class IBMiContent {
         await this.ibmi.sendCommand({ command: `rm -f ${Tools.escapePath(tempRemote)}` });
     }
     async getLibraries(filter = "*") {
-        const libFilter = filter === "*" ? "*ALL" : filter;
-        const rows = await this.ibmi.runSQL(`select OBJNAME, OBJTEXT from table(QSYS2.OBJECT_STATISTICS(${Tools.sqlString(libFilter)}, 'LIB', '*ALLSIMPLE'))`);
+        const normalized = String(filter || "*").trim().toUpperCase() || "*";
+        let sql;
+        if (normalized === "*" || normalized === "*ALL") {
+            sql = `select OBJNAME, OBJTEXT from table(QSYS2.OBJECT_STATISTICS('*ALL', 'LIB', '*ALLSIMPLE'))`;
+        }
+        else if (normalized.includes("*")) {
+            // Generic filter such as DEV*: libraries are *LIB objects in QSYS, so list
+            // those and match the name with LIKE.
+            if (!/^[A-Z0-9#@$_.*]{1,11}$/.test(normalized))
+                throw new Error(`Invalid library filter: ${filter}`);
+            const pattern = normalized.replace(/[!%_]/g, c => `!${c}`).replace(/\*/g, "%");
+            sql = `select OBJNAME, OBJTEXT from table(QSYS2.OBJECT_STATISTICS('QSYS', '*LIB', '*ALLSIMPLE')) ` +
+                `where OBJNAME like ${Tools.sqlString(pattern)} escape '!' order by OBJNAME`;
+        }
+        else {
+            sql = `select OBJNAME, OBJTEXT from table(QSYS2.OBJECT_STATISTICS(${Tools.sqlString(normalized)}, 'LIB', '*ALLSIMPLE'))`;
+        }
+        const rows = await this.ibmi.runSQL(sql);
         return rows.map(r => ({
             library: String(r.OBJNAME),
             name: String(r.OBJNAME),
@@ -208,6 +236,55 @@ export class IBMiContent {
             text: String(r.PARTITION_TEXT || "")
         }));
     }
+    async getMemberListPage(options) {
+        const lib = this.requireQsysName(options.library, "library");
+        const file = this.requireQsysName(options.sourceFile, "sourceFile");
+        const limit = Math.max(1, Math.min(500, Math.floor(options.limit || 50)));
+        const conditions = [
+            `P.SYSTEM_TABLE_SCHEMA=${Tools.sqlString(lib)}`,
+            `P.SYSTEM_TABLE_NAME=${Tools.sqlString(file)}`,
+            `P.SYSTEM_TABLE_MEMBER <> ''`
+        ];
+        if (options.member) {
+            conditions.push(`P.SYSTEM_TABLE_MEMBER=${Tools.sqlString(this.requireQsysName(options.member, "member"))}`);
+        }
+        if (options.memberPrefix) {
+            conditions.push(`P.SYSTEM_TABLE_MEMBER LIKE ${Tools.sqlString(`${this.normalizeSearchValue(options.memberPrefix)}%`)}`);
+        }
+        if (options.memberContains) {
+            conditions.push(`P.SYSTEM_TABLE_MEMBER LIKE ${Tools.sqlString(`%${this.normalizeSearchValue(options.memberContains)}%`)}`);
+        }
+        if (options.sourceTypes?.length) {
+            const sourceTypes = options.sourceTypes.map(value => this.normalizeSourceType(value));
+            conditions.push(`P.SOURCE_TYPE IN (${sourceTypes.map(Tools.sqlString).join(", ")})`);
+        }
+        if (options.changedSince) {
+            const changedSince = new Date(options.changedSince);
+            if (Number.isNaN(changedSince.getTime()))
+                throw new Error(`Invalid changedSince timestamp: ${options.changedSince}`);
+            const sqlTimestamp = changedSince.toISOString().slice(0, 23).replace("T", " ");
+            conditions.push(`P.LAST_SOURCE_UPDATE_TIMESTAMP >= timestamp(${Tools.sqlString(sqlTimestamp)})`);
+        }
+        if (options.cursor) {
+            const cursor = this.decodeMemberCursor(options.cursor);
+            conditions.push(`P.SYSTEM_TABLE_MEMBER > ${Tools.sqlString(cursor)}`);
+        }
+        const rows = await this.ibmi.runSQL(`select P.SYSTEM_TABLE_MEMBER, P.SOURCE_TYPE, P.PARTITION_TEXT, P.NUMBER_ROWS, ` +
+            `P.LAST_SOURCE_UPDATE_TIMESTAMP, T.ROW_LENGTH from QSYS2.SYSPARTITIONSTAT P ` +
+            `left join QSYS2.SYSTABLES T on T.SYSTEM_TABLE_SCHEMA=P.SYSTEM_TABLE_SCHEMA and T.SYSTEM_TABLE_NAME=P.SYSTEM_TABLE_NAME ` +
+            `where ${conditions.join(" and ")} order by P.SYSTEM_TABLE_MEMBER fetch first ${limit + 1} rows only`);
+        const hasMore = rows.length > limit;
+        const selected = rows.slice(0, limit);
+        const items = selected.map(row => this.memberMetadataFromRow(lib, file, row));
+        const last = items.at(-1);
+        return {
+            items,
+            returned: items.length,
+            hasMore,
+            ...(hasMore && last ? { nextCursor: this.encodeMemberCursor(last.name) } : {}),
+            observedAt: new Date().toISOString()
+        };
+    }
     async getMemberInfo(library, sourceFile, member) {
         const lib = this.requireQsysName(library, "library");
         const file = this.requireQsysName(sourceFile, "sourceFile");
@@ -224,23 +301,163 @@ export class IBMiContent {
             text: String(row.PARTITION_TEXT || "")
         };
     }
-    async downloadMemberContentWithDates(library, sourceFile, member) {
+    async getMemberMetadata(library, sourceFile, member) {
         const lib = this.requireQsysName(library, "library");
         const file = this.requireQsysName(sourceFile, "sourceFile");
         const mbr = this.requireQsysName(member, "member");
-        const tempLib = await this.getTempLibrary();
-        if (!tempLib)
-            return undefined;
-        const alias = makeAliasName(`${lib}/${file}/${mbr}`);
-        const aliasPath = `${tempLib}.${alias}`;
+        const rows = await this.ibmi.runSQL(`select P.SYSTEM_TABLE_MEMBER, P.SOURCE_TYPE, P.PARTITION_TEXT, P.NUMBER_ROWS, ` +
+            `P.LAST_SOURCE_UPDATE_TIMESTAMP, T.ROW_LENGTH from QSYS2.SYSPARTITIONSTAT P ` +
+            `left join QSYS2.SYSTABLES T on T.SYSTEM_TABLE_SCHEMA=P.SYSTEM_TABLE_SCHEMA and T.SYSTEM_TABLE_NAME=P.SYSTEM_TABLE_NAME ` +
+            `where P.SYSTEM_TABLE_SCHEMA=${Tools.sqlString(lib)} and P.SYSTEM_TABLE_NAME=${Tools.sqlString(file)} ` +
+            `and P.SYSTEM_TABLE_MEMBER=${Tools.sqlString(mbr)} fetch first 1 row only`);
+        return rows[0] ? this.memberMetadataFromRow(lib, file, rows[0]) : undefined;
+    }
+    async resolveMembers(options) {
+        const lib = this.requireQsysName(options.library, "library");
+        const member = this.requireQsysName(options.member, "member");
+        const limit = Math.max(1, Math.min(50, Math.floor(options.limit || 20)));
+        const conditions = [
+            `P.SYSTEM_TABLE_SCHEMA=${Tools.sqlString(lib)}`,
+            `P.SYSTEM_TABLE_MEMBER=${Tools.sqlString(member)}`
+        ];
+        if (options.candidateSourceFiles?.length) {
+            const files = options.candidateSourceFiles.map(value => this.requireQsysName(value, "candidateSourceFile"));
+            conditions.push(`P.SYSTEM_TABLE_NAME IN (${files.map(Tools.sqlString).join(", ")})`);
+        }
+        if (options.sourceTypes?.length) {
+            const types = options.sourceTypes.map(value => this.normalizeSourceType(value));
+            conditions.push(`P.SOURCE_TYPE IN (${types.map(Tools.sqlString).join(", ")})`);
+        }
+        const rows = await this.ibmi.runSQL(`select P.SYSTEM_TABLE_NAME, P.SYSTEM_TABLE_MEMBER, P.SOURCE_TYPE, P.PARTITION_TEXT, P.NUMBER_ROWS, ` +
+            `P.LAST_SOURCE_UPDATE_TIMESTAMP, T.ROW_LENGTH from QSYS2.SYSPARTITIONSTAT P ` +
+            `left join QSYS2.SYSTABLES T on T.SYSTEM_TABLE_SCHEMA=P.SYSTEM_TABLE_SCHEMA and T.SYSTEM_TABLE_NAME=P.SYSTEM_TABLE_NAME ` +
+            `where ${conditions.join(" and ")} order by P.SYSTEM_TABLE_NAME fetch first ${limit + 1} rows only`);
+        return rows.slice(0, limit).map(row => this.memberMetadataFromRow(lib, String(row.SYSTEM_TABLE_NAME || ""), row));
+    }
+    async getMemberSnapshot(library, sourceFile, member, forceFresh = false) {
+        const lib = this.requireQsysName(library, "library");
+        const file = this.requireQsysName(sourceFile, "sourceFile");
+        const mbr = this.requireQsysName(member, "member");
+        const identityKey = `${lib}/${file}/${mbr}`;
+        if (!forceFresh) {
+            const cached = this.peekCachedSnapshot(identityKey);
+            if (cached) {
+                // Cache contract: a hit is only served after the cheap change marker
+                // still matches, so edits made outside this server are seen at once.
+                const current = await this.getMemberMetadata(lib, file, mbr);
+                if (!current) {
+                    this.invalidateMemberSnapshot(lib, file, mbr);
+                    throw new Error(`${mbr} in ${lib}/${file} not found`);
+                }
+                if (sameChangeMarker(cached.metadata, current)) {
+                    return { ...cached, metadata: current, validatedAt: new Date().toISOString(), cacheStatus: "hit" };
+                }
+                this.invalidateMemberSnapshot(lib, file, mbr);
+            }
+            const inflight = this.snapshotInflight.get(identityKey);
+            if (inflight)
+                return { ...(await inflight), cacheStatus: "coalesced" };
+        }
+        // An invalidation (write, rename, delete) while this load is in flight
+        // bumps the generation, and the possibly stale result is then not cached.
+        const generation = this.snapshotGeneration.get(identityKey) || 0;
+        const loading = this.loadMemberSnapshot(lib, file, mbr);
+        this.snapshotInflight.set(identityKey, loading);
         try {
-            await this.ibmi.runSQL(`CREATE OR REPLACE ALIAS ${aliasPath} for \"${lib}\".\"${file}\"(\"${mbr}\")`);
+            const snapshot = await loading;
+            if ((this.snapshotGeneration.get(identityKey) || 0) === generation) {
+                this.cacheSnapshot(identityKey, snapshot);
+            }
+            return snapshot;
         }
-        catch {
-            // ignore, alias might already exist
+        finally {
+            if (this.snapshotInflight.get(identityKey) === loading)
+                this.snapshotInflight.delete(identityKey);
+        }
+    }
+    /**
+     * Cheap version information for metadata-only reads. Returns the member's
+     * catalog metadata and, when a cached snapshot is still valid for the
+     * current change marker, that snapshot. Never downloads member content.
+     */
+    async getMemberVersionInfo(library, sourceFile, member) {
+        const lib = this.requireQsysName(library, "library");
+        const file = this.requireQsysName(sourceFile, "sourceFile");
+        const mbr = this.requireQsysName(member, "member");
+        const identityKey = `${lib}/${file}/${mbr}`;
+        const metadata = await this.getMemberMetadata(lib, file, mbr);
+        const observedAt = new Date().toISOString();
+        if (!metadata) {
+            this.invalidateMemberSnapshot(lib, file, mbr);
+            throw new Error(`${mbr} in ${lib}/${file} not found`);
+        }
+        const cached = this.peekCachedSnapshot(identityKey);
+        if (cached && sameChangeMarker(cached.metadata, metadata)) {
+            return { metadata, observedAt, snapshot: { ...cached, metadata, validatedAt: observedAt, cacheStatus: "hit" } };
+        }
+        return { metadata, observedAt };
+    }
+    invalidateMemberSnapshot(library, sourceFile, member) {
+        const identityKey = `${String(library).trim().toUpperCase()}/${String(sourceFile).trim().toUpperCase()}/${String(member).trim().toUpperCase()}`;
+        this.snapshotGeneration.set(identityKey, (this.snapshotGeneration.get(identityKey) || 0) + 1);
+        for (const [key, entry] of this.snapshotCache) {
+            if (entry.identityKey === identityKey)
+                this.snapshotCache.delete(key);
         }
-        const recordLength = await this.getRecordLength(aliasPath, lib, file);
-        const rows = await this.ibmi.runSQL(`select case when locate('40',hex(srcdat)) > 0 then 0 else srcdat end as SRCDAT, srcseq, srcdta from ${aliasPath}`);
+        this.snapshotLatestKey.delete(identityKey);
+        // Later readers must not coalesce onto a load that started before the change.
+        this.snapshotInflight.delete(identityKey);
+    }
+    peekCachedSnapshot(identityKey) {
+        const latestKey = this.snapshotLatestKey.get(identityKey);
+        if (!latestKey)
+            return undefined;
+        const entry = this.snapshotCache.get(latestKey);
+        if (!entry || entry.expiresAt <= Date.now()) {
+            this.snapshotCache.delete(latestKey);
+            this.snapshotLatestKey.delete(identityKey);
+            return undefined;
+        }
+        // Refresh LRU order.
+        this.snapshotCache.delete(latestKey);
+        this.snapshotCache.set(latestKey, entry);
+        return entry.snapshot;
+    }
+    cacheSnapshot(identityKey, snapshot) {
+        // Without an authoritative change marker a hit could never be validated.
+        if (!snapshot.metadata.lastChanged)
+            return;
+        for (const [key, entry] of this.snapshotCache) {
+            if (entry.identityKey === identityKey)
+                this.snapshotCache.delete(key);
+        }
+        const key = `${identityKey}/${snapshot.metadata.lastChanged}`;
+        this.snapshotCache.set(key, { snapshot, identityKey, expiresAt: Date.now() + this.snapshotCacheTtlMs });
+        this.snapshotLatestKey.set(identityKey, key);
+        while (this.snapshotCache.size > this.snapshotCacheMax) {
+            const oldest = this.snapshotCache.keys().next().value;
+            if (!oldest)
+                break;
+            const evicted = this.snapshotCache.get(oldest);
+            this.snapshotCache.delete(oldest);
+            if (evicted && this.snapshotLatestKey.get(evicted.identityKey) === oldest) {
+                this.snapshotLatestKey.delete(evicted.identityKey);
+            }
+        }
+    }
+    async downloadMemberContentWithDates(library, sourceFile, member) {
+        const lib = this.requireQsysName(library, "library");
+        const file = this.requireQsysName(sourceFile, "sourceFile");
+        const mbr = this.requireQsysName(member, "member");
+        // Db2 for i requires an alias to address a non-default member. Keep the
+        // alias in QTEMP and create/read it in the same QZDFMDB2 job so no
+        // persistent ILEDITOR object or cross-job alias lookup is involved.
+        const alias = makeAliasName(`${lib}/${file}/${mbr}`);
+        const aliasPath = `QTEMP.\"${alias}\"`;
+        const recordLength = await this.getRecordLength(undefined, lib, file);
+        const rows = await this.ibmi.runSQL(`create or replace alias ${aliasPath} for \"${lib}\".\"${file}\"(\"${mbr}\");\n` +
+            `select case when locate('40',hex(srcdat)) > 0 then 0 else srcdat end as SRCDAT, srcseq, srcdta ` +
+            `from ${aliasPath} as M order by rrn(M)`);
         if (!rows || rows.length === 0) {
             return "";
         }
@@ -254,18 +471,14 @@ export class IBMiContent {
         const lib = this.requireQsysName(library, "library");
         const file = this.requireQsysName(sourceFile, "sourceFile");
         const mbr = this.requireQsysName(member, "member");
-        const tempLib = await this.getTempLibrary();
-        if (!tempLib) {
-            throw new Error(`Temp library is not available for source-date updates.`);
-        }
         const alias = makeAliasName(`${lib}/${file}/${mbr}`);
-        const aliasPath = `${tempLib}.${alias}`;
+        const aliasPath = `QTEMP.\"${alias}\"`;
         const baseKey = `${lib}/${file}/${mbr}`;
         if (!this.sourceDates.getBaseSource(baseKey)) {
-            await this.downloadMemberContentWithDates(lib, file, mbr);
+            await this.loadMemberSnapshotViaSql(lib, file, mbr);
         }
         const sourceDates = this.sourceDates.calcNewSourceDates(baseKey, body);
-        const recordLength = this.sourceDates.getRecordLength(baseKey) || await this.getRecordLength(aliasPath, lib, file);
+        const recordLength = this.sourceDates.getRecordLength(baseKey) || await this.getRecordLength(undefined, lib, file);
         const sourceData = body.split(`\n`);
         const decimalSequence = sourceData.length >= 10000;
         const rows = [];
@@ -280,6 +493,7 @@ export class IBMiContent {
         }
         const tempTable = `QTEMP.NEWMEMBER`;
         const statements = [
+            `CREATE OR REPLACE ALIAS ${aliasPath} FOR \"${lib}\".\"${file}\"(\"${mbr}\");`,
             `CREATE TABLE ${tempTable} LIKE \"${lib}\".\"${file}\";`
         ];
         const rowLength = recordLength + 55;
@@ -303,14 +517,16 @@ export class IBMiContent {
     }
     async getRecordLength(aliasPath, lib, file) {
         let recordLength = 80;
-        try {
-            const res = await this.ibmi.runSQL(`select length(SRCDTA) as LENGTH from ${aliasPath} fetch first 1 rows only`);
-            if (res.length > 0 && res[0].LENGTH) {
-                recordLength = Number(res[0].LENGTH);
-                return recordLength;
+        if (aliasPath) {
+            try {
+                const res = await this.ibmi.runSQL(`select length(SRCDTA) as LENGTH from ${aliasPath} fetch first 1 rows only`);
+                if (res.length > 0 && res[0].LENGTH) {
+                    recordLength = Number(res[0].LENGTH);
+                    return recordLength;
+                }
             }
+            catch { }
         }
-        catch { }
         try {
             const res = await this.ibmi.runSQL(`select row_length-12 as LENGTH from QSYS2.SYSTABLES where SYSTEM_TABLE_SCHEMA = ${Tools.sqlString(lib)} and SYSTEM_TABLE_NAME = ${Tools.sqlString(file)} fetch first 1 rows only`);
             if (res.length > 0 && res[0].LENGTH) {
@@ -320,16 +536,121 @@ export class IBMiContent {
         catch { }
         return recordLength;
     }
+    async loadMemberSnapshot(lib, file, mbr) {
+        if (this.config.enableSourceDates) {
+            try {
+                return await this.loadMemberSnapshotViaSql(lib, file, mbr);
+            }
+            catch (error) {
+                return this.loadMemberSnapshotViaStreamFile(lib, file, mbr, error);
+            }
+        }
+        return this.loadMemberSnapshotViaStreamFile(lib, file, mbr);
+    }
+    async loadMemberSnapshotViaSql(lib, file, mbr) {
+        const alias = makeAliasName(`${lib}/${file}/${mbr}`);
+        const aliasPath = `QTEMP.\"${alias}\"`;
+        const rows = await this.ibmi.runSQL(`create or replace alias ${aliasPath} for \"${lib}\".\"${file}\"(\"${mbr}\");\n` +
+            `select case when locate('40',hex(M.srcdat)) > 0 then 0 else M.srcdat end as SRCDAT, M.srcseq, M.srcdta, ` +
+            `P.SYSTEM_TABLE_MEMBER, P.SOURCE_TYPE, P.PARTITION_TEXT, P.NUMBER_ROWS, P.LAST_SOURCE_UPDATE_TIMESTAMP, T.ROW_LENGTH ` +
+            `from ${aliasPath} as M cross join QSYS2.SYSPARTITIONSTAT P ` +
+            `left join QSYS2.SYSTABLES T on T.SYSTEM_TABLE_SCHEMA=P.SYSTEM_TABLE_SCHEMA and T.SYSTEM_TABLE_NAME=P.SYSTEM_TABLE_NAME ` +
+            `where P.SYSTEM_TABLE_SCHEMA=${Tools.sqlString(lib)} and P.SYSTEM_TABLE_NAME=${Tools.sqlString(file)} ` +
+            `and P.SYSTEM_TABLE_MEMBER=${Tools.sqlString(mbr)} order by rrn(M)`);
+        let metadata;
+        if (rows.length === 0) {
+            const emptyMetadata = await this.getMemberMetadata(lib, file, mbr);
+            if (!emptyMetadata)
+                throw new Error(`${mbr} in ${lib}/${file} not found`);
+            metadata = emptyMetadata;
+        }
+        else {
+            metadata = this.memberMetadataFromRow(lib, file, rows[0]);
+        }
+        const sourceDates = rows.map(row => String(row.SRCDAT).padStart(6, "0"));
+        const content = rows.map(row => String(row.SRCDTA ?? "")).join("\n");
+        const snapshot = this.makeMemberSnapshot(lib, file, mbr, content, metadata, "sql-member", []);
+        // The diff base must match what callers see and send back (trimmed lines),
+        // otherwise every padded line would look changed and lose its date.
+        this.sourceDates.setBase(`${lib}/${file}/${mbr}`, snapshot.content, sourceDates, metadata.recordLength || 80);
+        return snapshot;
+    }
+    async loadMemberSnapshotViaStreamFile(lib, file, mbr, sqlError) {
+        const metadataBefore = await this.getMemberMetadata(lib, file, mbr);
+        if (!metadataBefore)
+            throw new Error(`${mbr} in ${lib}/${file} not found`);
+        const content = await this.downloadMemberContentViaStreamFile(lib, file, mbr);
+        const metadataAfter = await this.getMemberMetadata(lib, file, mbr);
+        if (!metadataAfter)
+            throw new Error(`${mbr} in ${lib}/${file} was removed during read`);
+        if (metadataBefore.lastChanged && metadataAfter.lastChanged && metadataBefore.lastChanged !== metadataAfter.lastChanged) {
+            throw new Error(`Source changed during read: ${lib}/${file}(${mbr})`);
+        }
+        return this.makeMemberSnapshot(lib, file, mbr, content, metadataAfter, "cpytostmf", sqlError ? [`Source-date SQL read failed; used complete CPYTOSTMF fallback: ${sqlError?.message || String(sqlError)}`] : []);
+    }
+    makeMemberSnapshot(lib, file, mbr, rawContent, metadata, transport, warnings) {
+        const { content, lines } = normalizeMemberContent(rawContent, transport);
+        const sha256 = crypto.createHash("sha256").update(content, "utf8").digest("hex");
+        const marker = metadata.lastChanged || "unknown";
+        return {
+            identity: { library: lib, sourceFile: file, member: mbr },
+            content,
+            lines,
+            metadata,
+            sha256,
+            version: `${marker}:${sha256.slice(0, 16)}`,
+            observedAt: new Date().toISOString(),
+            complete: true,
+            transport,
+            warnings,
+            cacheStatus: "miss"
+        };
+    }
+    memberMetadataFromRow(lib, file, row) {
+        const rowLength = Number(row.ROW_LENGTH || 0);
+        return {
+            library: lib,
+            file: this.ibmi.upperCaseName(file),
+            name: String(row.SYSTEM_TABLE_MEMBER || ""),
+            extension: String(row.SOURCE_TYPE || ""),
+            text: String(row.PARTITION_TEXT || ""),
+            lines: Number(row.NUMBER_ROWS || 0),
+            rowCount: Number(row.NUMBER_ROWS || 0),
+            ...(row.LAST_SOURCE_UPDATE_TIMESTAMP ? { lastChanged: String(row.LAST_SOURCE_UPDATE_TIMESTAMP) } : {}),
+            ...(rowLength > 0 ? { recordLength: Math.max(0, rowLength - 12) } : {})
+        };
+    }
+    normalizeSearchValue(value) {
+        return String(value || "").trim().toUpperCase().replace(/[%_]/g, "");
+    }
+    encodeMemberCursor(member) {
+        return Buffer.from(JSON.stringify({ v: 1, member }), "utf8").toString("base64url");
+    }
+    decodeMemberCursor(cursor) {
+        try {
+            const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+            if (parsed?.v !== 1 || typeof parsed.member !== "string")
+                throw new Error("bad cursor");
+            return this.requireQsysName(parsed.member, "cursor member");
+        }
+        catch {
+            throw new Error("Invalid member-list cursor");
+        }
+    }
     async createLibrary(library) {
         this.assertWritable();
         const lib = this.requireQsysName(library, "library");
-        return this.ibmi.sendQsh({ command: `system \"CRTLIB LIB(${lib})\"` });
+        return this.runClViaQsh(`CRTLIB LIB(${lib})`, "CRTLIB");
     }
     async createSourceFile(library, file, rcdlen = 112) {
         this.assertWritable();
         const lib = this.requireQsysName(library, "library");
         const src = this.requireQsysName(file, "sourceFile");
-        return this.ibmi.sendQsh({ command: `system \"CRTSRCPF FILE(${lib}/${src}) RCDLEN(${rcdlen})\"` });
+        const length = Number(rcdlen);
+        if (!Number.isInteger(length) || length < 13 || length > 32766) {
+            throw new Error(`Invalid rcdlen: ${rcdlen}`);
+        }
+        return this.runClViaQsh(`CRTSRCPF FILE(${lib}/${src}) RCDLEN(${length})`, "CRTSRCPF");
     }
     async createMember(library, file, member, srctype) {
         this.assertWritable();
@@ -337,7 +658,12 @@ export class IBMiContent {
         const src = this.requireQsysName(file, "sourceFile");
         const mbr = this.requireQsysName(member, "member");
         const type = this.normalizeSourceType(srctype);
-        return this.ibmi.sendQsh({ command: `system \"ADDPFM FILE(${lib}/${src}) MBR(${mbr}) SRCTYPE(${type})\"` });
+        try {
+            return await this.runClViaQsh(`ADDPFM FILE(${lib}/${src}) MBR(${mbr}) SRCTYPE(${type})`, "ADDPFM");
+        }
+        finally {
+            this.invalidateMemberSnapshot(lib, src, mbr);
+        }
     }
     async renameMember(library, file, member, newMember) {
         this.assertWritable();
@@ -345,14 +671,37 @@ export class IBMiContent {
         const src = this.requireQsysName(file, "sourceFile");
         const mbr = this.requireQsysName(member, "member");
         const newMbr = this.requireQsysName(newMember, "newMember");
-        return this.ibmi.sendQsh({ command: `system \"RNMM FILE(${lib}/${src}) MBR(${mbr}) NEWMBR(${newMbr})\"` });
+        try {
+            return await this.runClViaQsh(`RNMM FILE(${lib}/${src}) MBR(${mbr}) NEWMBR(${newMbr})`, "RNMM");
+        }
+        finally {
+            this.invalidateMemberSnapshot(lib, src, mbr);
+            this.invalidateMemberSnapshot(lib, src, newMbr);
+        }
     }
     async deleteMember(library, file, member) {
         this.assertWritable();
         const lib = this.requireQsysName(library, "library");
         const src = this.requireQsysName(file, "sourceFile");
         const mbr = this.requireQsysName(member, "member");
-        return this.ibmi.sendQsh({ command: `system \"RMVM FILE(${lib}/${src}) MBR(${mbr})\"` });
+        try {
+            return await this.runClViaQsh(`RMVM FILE(${lib}/${src}) MBR(${mbr})`, "RMVM");
+        }
+        finally {
+            this.invalidateMemberSnapshot(lib, src, mbr);
+        }
+    }
+    // Runs a CL command through qsh's `system` utility and throws when it fails.
+    // `system` exits non-zero when the command ends with an escape message.
+    // '$' is escaped because names such as $ABC would otherwise be expanded by
+    // the shell inside the double-quoted argument.
+    async runClViaQsh(command, label) {
+        const result = await this.ibmi.sendQsh({ command: `system \"${IBMiClient.escapeForShell(command)}\"` });
+        if (!result || result.code !== 0) {
+            const detail = String(result?.stderr || result?.stdout || "").trim();
+            throw new Error(`${label} failed (exit ${result?.code ?? "unknown"})${detail ? `: ${detail}` : ""}`);
+        }
+        return result;
     }
     async createTempFile() {
         const dir = await fs.mkdtemp(path.join(os.tmpdir(), "mcpfori-"));
@@ -386,6 +735,29 @@ export class IBMiContent {
         }
     }
 }
+/**
+ * Normalizes member text so both read transports produce the same content,
+ * SHA-256 and version: line endings become LF, trailing blanks are removed
+ * from every line (the SQL path returns CHAR-padded SRCDTA, CPYTOSTMF output
+ * is trimmed) and the record terminator CPYTOSTMF writes after the last
+ * record is dropped.
+ */
+export function normalizeMemberContent(rawContent, transport) {
+    let text = String(rawContent ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    if (transport === "cpytostmf" && text.endsWith("\n"))
+        text = text.slice(0, -1);
+    const lines = text === "" ? [] : text.split("\n").map(line => line.trimEnd());
+    return { content: lines.join("\n"), lines };
+}
+function sameChangeMarker(cached, current) {
+    if (!cached.lastChanged || !current.lastChanged)
+        return false;
+    if (cached.lastChanged !== current.lastChanged)
+        return false;
+    if (typeof cached.rowCount === "number" && typeof current.rowCount === "number" && cached.rowCount !== current.rowCount)
+        return false;
+    return true;
+}
 function escapeString(val) {
     return val.replace(/[\0\n\r\b\t'\x1a]/g, function (s) {
         switch (s) {