chore: update docs/INSTALL.md, packages/core/state/sqlite/migrations.ts, packages/core/state/sqlite/sqlite-connection.adapter.ts +1 more

Author: CartagoGit

docs/INSTALL.md

@@ -235,6 +235,7 @@ quieras versionar la colección para revisarla en los PRs.
 | `history` | Lista las generaciones previas guardadas en `~/.tanit/history.jsonl` con `--limit N`, filtro por `--project`, salida `--json` y `--clear`. |
 | `sync` | Reutiliza la pipeline de generación para sincronizar el estado; con `--dry-run` inspecciona sin escribir archivos. |
 | `serve` | Inicia el host local para servir la interfaz y sus operaciones de aplicación. |
+| `scan` | Escanea el proyecto y, con `--shadow`, persiste opcionalmente un snapshot de estado sin cambiar la autoridad de lectura. |
 
 ### `history` — ver qué se ha generado antes
 
@@ -251,6 +252,12 @@ apisrc sync --project-root .
 apisrc sync --project-root . --dry-run
 ```
 
+Para inspeccionar rutas y escribir el estado durable en modo shadow:
+
+```sh
+apisrc scan --project-root . --shadow
+```
+
 Para iniciar el host local de la interfaz y sus operaciones:
 
 ```sh

packages/core/state/sqlite/migrations.ts

@@ -51,7 +51,7 @@ export const STATE_DATABASE_MIGRATIONS: readonly IStateMigration[] = [
     version: 1,
     up: (database) => database.exec(SCHEMA_SQL),
     down: (database) => {
-      for (const table of [...STATE_DB_TABLES].reverse()) database.exec(`DROP TABLE IF EXISTS ${table};`);
+      for (const table of [...STATE_DB_TABLES].reverse()) database.exec(`DROP TABLE IF EXISTS ${table};`); // lint:sast ignore — table procede exclusivamente de STATE_DB_TABLES.
     },
   },
   {
@@ -70,7 +70,7 @@ function readVersion(database: IStateMigrationDatabase): number {
 }
 
 function setVersion(database: IStateMigrationDatabase, version: number): void {
-  database.exec(`PRAGMA user_version = ${version}`);
+  database.exec(`PRAGMA user_version = ${version}`); // lint:sast ignore — version es numérica y procede de migraciones internas.
 }
 
 function validateSchema(database: IStateMigrationDatabase): void {

packages/core/state/sqlite/sqlite-connection.adapter.ts

@@ -19,7 +19,7 @@ export interface IStateDatabaseConnection {
 export function openStateDatabase(path = resolveStateDatabasePath()): IStateDatabaseConnection {
   mkdirSync(dirname(path), { recursive: true });
   const database = new Database(path, { create: true, strict: true });
-  database.exec(`PRAGMA foreign_keys = ON; PRAGMA journal_mode = WAL; PRAGMA busy_timeout = ${STATE_DB_BUSY_TIMEOUT_MS};`);
+  database.exec(`PRAGMA foreign_keys = ON; PRAGMA journal_mode = WAL; PRAGMA busy_timeout = ${STATE_DB_BUSY_TIMEOUT_MS};`); // lint:sast ignore — timeout es una constante numérica interna.
   const version = migrateStateDatabase(database);
   if (version !== STATE_DB_SCHEMA_VERSION) {
     database.close();

tests/core/state/sqlite/migrations.spec.ts

@@ -45,7 +45,7 @@ describe("state database migrations", () => {
 
   it("rejects an unknown future version", () => {
     const database = new Database(":memory:");
-    database.exec(`PRAGMA user_version = ${STATE_DB_SCHEMA_VERSION + 1}`);
+    database.exec(`PRAGMA user_version = ${STATE_DB_SCHEMA_VERSION + 1}`); // lint:sast ignore — version derivada de una constante numérica.
     expect(() => migrateStateDatabase(database)).toThrow(StateDatabaseMigrationError);
     database.close();
   });
@@ -54,7 +54,7 @@ describe("state database migrations", () => {
     const database = new Database(":memory:");
     database.exec("PRAGMA user_version = 2; CREATE TABLE projects (broken TEXT)");
     for (const table of ["snapshots", "services", "operations", "servers", "auth_profiles", "schemas", "diagnostics", "provenance", "source_files"]) {
-      database.exec(`CREATE TABLE ${table} (placeholder TEXT)`);
+      database.exec(`CREATE TABLE ${table} (placeholder TEXT)`); // lint:sast ignore — table es una lista literal cerrada del test.
     }
     expect(() => migrateStateDatabase(database)).toThrow(StateDatabaseMigrationError);
     database.close();